Experience & Runtime API

웹툰, FMV 게임, 캐릭터 챗봇과 선형 영상을 하나의 entitlement 기반 API로 조회하고 실행합니다. 카탈로그에는 catalog:read, 세션과 상호작용에는 runtime:session 스코프가 필요합니다.

엔드포인트

메서드	경로	Runtime 토큰
GET	`/catalog/experiences`	아니오
GET	`/catalog/experiences/{experience_id}`	아니오
GET	`/catalog/experiences/{experience_id}/units`	아니오
POST	`/runtime/sessions`	응답에서 한 번 발급
GET	`/runtime/sessions/{session_id}`	필수
POST	`/runtime/sessions/{session_id}/revoke`	필수
GET	`/runtime/sessions/{session_id}/manifest`	필수
POST	`/runtime/sessions/{session_id}/fmv/decisions`	필수
POST	`/runtime/sessions/{session_id}/chat/turns`	필수

Experience 카탈로그

지역, 언어, 플랫폼과 capability는 반드시 같은 offers[] 행 안에서 해석하세요. 서로 다른 offer나 rights package의 필드를 합쳐 새로운 허용 범위를 만들면 안 됩니다. 웹툰·FMV·캐릭터 챗 권한은 각각 명시 grant이며 기본값은 거부입니다.

curl "https://signal-partners.newunivers.ai/v1/catalog/experiences?experience_type=webtoon&territory=KR&language=ko&platform=web" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme"

Runtime 세션

curl -X POST "https://signal-partners.newunivers.ai/v1/runtime/sessions" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "X-NU-Request-Id: req_runtime_0001" \
  -H "Content-Type: application/json" \
  -d '{
    "experience_id": "exp_webtoon_01",
    "country": "KR",
    "language": "ko",
    "platform": "web",
    "viewer_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "expires_in": 1800
      }'

country, language, platform은 필수입니다.
요청 TTL은 60~3,600초이며 실제 만료는 entitlement, deal, rights 중 가장 이른 종료 시각을 넘지 않습니다.
session_token 원문은 생성 응답에만 나타나며 서버에는 해시만 저장됩니다.
이후 호출은 API 키와 X-NU-Runtime-Token을 함께 보내야 합니다.
세션 생성에는 안정적인 request ID를 권장하고, FMV 결정과 chat turn에는 반드시 보내야 합니다. revoke는 자체 멱등입니다.
권리·deal·entitlement는 매 호출마다 다시 검사되어 철회가 기존 세션에도 즉시 반영됩니다.

Manifest와 콘텐츠 경로

Manifest는 release에 고정된 안전한 logical_path만 반환합니다. 원본 bucket, storage key 또는 공개되지 않은 저장소 URL은 노출하지 않습니다. 실제 session-scoped 전송 URL은 별도 delivery plane이 제공될 때 추가됩니다.

FMV 결정

curl -X POST "https://signal-partners.newunivers.ai/v1/runtime/sessions/run_01/fmv/decisions" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "X-NU-Runtime-Token: nsp_rt_xxx" \
  -H "X-NU-Request-Id: req_fmv_0001" \
  -H "Content-Type: application/json" \
      -d '{"choice_id":"choice_left"}'

현재 노드에서 허용된 무조건 choice만 서버가 원자적으로 적용합니다. 동일 요청 ID의 재시도는 같은 결과를 반환하며, 다른 세션이나 payload에 재사용하면 409를 반환합니다.

캐릭터 대화

curl -X POST "https://signal-partners.newunivers.ai/v1/runtime/sessions/run_01/chat/turns" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "X-NU-Runtime-Token: nsp_rt_xxx" \
  -H "X-NU-Request-Id: req_chat_0001" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

현재 foundation은 text-only이며 PII와 설정된 turn/token budget을 입력·출력에서 검사합니다.
원문은 audit, event, usage metadata에 기록하지 않고 ChatTurn에는 목적별 HMAC 지문만 저장합니다.
Provider 호출 뒤 거절된 응답은 원문 없이 실제 소비 token과 비콘텐츠 거절 사유만 계량하며 세션 예산에 포함합니다.
성공 응답은 멱등 재생을 위해 암호화되어 최대 24시간 임시 보존된 뒤 만료됩니다.
승인된 provider가 없거나 실패하면 임의 응답 없이 503 service_unavailable로 종료합니다.