FECINE OPEN API v1.1.0

API 명세서

대본부터 최종 영상까지. FECINE API로 제작 워크플로를 연결하세요.

인증하기

FECINE API Key를 Bearer 토큰으로 사용하세요. 명세 열람에는 계정이 필요하지 않습니다.

작품 만들고 실행하기

작품을 만든 뒤 대본·자료를 업로드하고 캐릭터·배경 씬·소품·그리드를 등록합니다. 에피소드와 씬을 만들고 참조 항목을 연결한 다음 씬 영상을 생성합니다. 각 씬의 테이크를 선택한 뒤 최종본을 내보내세요. 생성 작업은 완료를 확인한 뒤 다음 단계로 진행하고, 편집 요청에는 최신 revision을 보냅니다. 업로드한 대본으로 구성을 만들려면 별도로 ‘작품 빌드’를 실행할 수 있습니다.

결과 받기

작업 상태를 조회하거나 Webhook을 받으세요. 자산 ID로 서명된 다운로드 링크를 조회할 수 있습니다.

첫 번째 요청

curl -X GET 'https://YOUR_FECINE_HOST/api/v1/capabilities' \
  -H 'Authorization: Bearer YOUR_FECINE_API_KEY'

GET /api/v1/capabilities

REFERENCE

API 명세

FECINE API Key

FECINE 오류입니다. 문의 시 request_id를 전달하세요.

JSON 예제를 복사한 뒤 ID·URL·내용을 실제 값으로 바꿔 사용하세요.

지원 기능

GET/api/v1/capabilities지금 쓸 수 있는 기능 보기

현재 API 환경에서 사용할 수 있는 기능·모델·업로드 형식과 제작 한도를 조회합니다.

필요 권한: projects:read

매개변수

매개변수 없음

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "studio_workflow": {
          "equivalent": false,
          "stages": [
            "script"
          ],
          "project_access": "read_only",
          "gaps": [
            "example"
          ]
        },
        "template_id": "example",
        "template_version": 1,
        "enabled": false,
        "stages": [
          "example"
        ],
        "output_profiles": [
          "example"
        ],
        "unsupported_reasons": [
          "example"
        ],
        "max_shots": 1,
        "max_episode_seconds": 1,
        "upload_mime_types": [
          "example"
        ],
        "max_upload_bytes": 1
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

서버 응답

작품·제작 자료

GET/api/v1/works내 작품 목록 보기

접근할 수 있는 작품 목록을 조회합니다. state로 활성·보관 상태를 고르고 cursor와 limit으로 나누어 조회할 수 있습니다.

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100
`state`query	문자열	선택	작품 상태입니다. active는 사용 중, archived는 보관 상태입니다. 허용값: active, archived

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "example",
        "revision": 1,
        "state": "active",
        "created_at": "2026-09-20T00:00:00Z",
        "client_reference": "example"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

cursor query limit query state query

서버 응답

POST/api/v1/works새 작품 만들기

입력한 name으로 새 작품을 만듭니다. 반환된 작품 ID로 자료를 등록하고 제작을 진행할 수 있습니다.

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`client_reference`	문자열	선택	사용자 시스템에서 이 요청을 찾기 위한 관리번호입니다. 예: order-1234. 중복 실행 방지용 키와는 별개입니다. 최대: 128자

첫 번째 요청 · JSON

{
  "name": "example"
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "example",
    "revision": 1,
    "state": "active",
    "created_at": "2026-09-20T00:00:00Z",
    "client_reference": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{project_id}작품 정보 보기

작품의 이름·상태·현재 revision을 조회합니다. 작품을 수정하거나 제작을 요청하기 전에 최신 버전을 확인할 때 사용합니다.

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "example",
    "revision": 1,
    "state": "active",
    "created_at": "2026-09-20T00:00:00Z",
    "client_reference": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *

서버 응답

PATCH/api/v1/works/{project_id}작품 정보 수정

작품 이름을 바꾸거나 상태를 active·archived로 변경합니다. If-Match에 최신 응답의 ETag를 넣어 주세요.

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`If-Match`header	문자열	필수	수정할 리소스를 먼저 조회하고, 응답 헤더의 ETag 값을 따옴표까지 그대로 넣으세요. 예: "3".

요청 본문

이름	타입	필수	설명
`name`	문자열	선택	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`state`	문자열	선택	작품 상태입니다. active는 사용 중, archived는 보관 상태입니다. 허용값: active, archived

첫 번째 요청 · JSON

{}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "example",
    "revision": 1,
    "state": "active",
    "created_at": "2026-09-20T00:00:00Z",
    "client_reference": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *If-Match header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{project_id}/resources올린 자료 목록 보기

작품에 등록된 대본·캐릭터·장면·소품·에피소드·샷 자료를 조회합니다. kind로 자료 종류를 선택할 수 있습니다.

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100
`kind`query	문자열	선택	생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 허용값: script, character, scene, prop, episode, shot

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "work_id": "11111111-1111-4111-8111-111111111111",
        "revision": 1,
        "content": {
          "kind": "script",
          "name": "example",
          "data": {
            "language": "example"
          }
        },
        "created_at": "2026-09-20T00:00:00Z"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *cursor query limit query kind query

서버 응답

POST/api/v1/works/{project_id}/resources대본·이미지 같은 자료 올리기

kind와 data로 대본 본문이나 샷 정보 같은 제작 자료를 작품에 등록합니다. 파일 자체를 전송하려면 /uploads를 사용하세요.

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`kind`	문자열	필수	kind = script생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: script
`name`	문자열	필수	kind = script목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = script선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.text`	문자열	선택	kind = script대본 내용을 일반 텍스트로 입력하세요. source_asset_id를 사용하는 요청에서는 둘 중 하나만 보내세요. 최소: 1자 최대: 900000자
`data.source_asset_id`	문자열	선택	kind = script대본 원본 파일의 에셋 id입니다. 직접 입력하는 text와 둘 중 하나만 보내세요. 형식: UUID (조회 응답의 id 사용)
`data.language`	문자열	필수	kind = script대본의 언어 코드입니다. 예: ko(한국어), en(영어). 최소: 2자 최대: 16자
`kind`	문자열	필수	kind = character생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: character
`name`	문자열	필수	kind = character목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = character선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = character대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = character이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = scene생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: scene
`name`	문자열	필수	kind = scene목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = scene선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = scene대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = scene이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = prop생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: prop
`name`	문자열	필수	kind = prop목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = prop선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = prop대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = prop이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = episode생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: episode
`name`	문자열	필수	kind = episode목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = episode선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.script_resource_id`	문자열	필수	kind = episode이 에피소드가 사용할 대본 리소스의 id입니다. 형식: UUID (조회 응답의 id 사용)
`data.sequence`	정수	필수	kind = episode같은 목록 안에서 배치할 순서입니다. 1부터 시작합니다. 최솟값: 1 최댓값: 100
`data.raw_content`	문자열	선택	kind = episode해당 에피소드에 속하는 대본 원문입니다. 최대: 20000자
`data.description`	문자열	선택	kind = episode대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`kind`	문자열	필수	kind = shot생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: shot
`name`	문자열	필수	kind = shot목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = shot선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.episode_id`	문자열	필수	kind = shot대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`data.scene_id`	문자열	선택	kind = shot대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`data.character_ids`	목록	선택	kind = shot샷에 등장하는 캐릭터 리소스의 id 목록입니다. 생략 시: [] 최대: 8개
`data.prop_ids`	목록	선택	kind = shot샷에서 사용하는 소품 리소스의 id 목록입니다. 생략 시: [] 최대: 8개
`data.description`	문자열	필수	kind = shot대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.video_prompt`	선택형	선택	kind = shot이 씬의 영상에 필요한 움직임, 카메라 동작과 연출을 적으세요.
`data.sequence`	정수	선택	kind = shot같은 목록 안에서 배치할 순서입니다. 1부터 시작합니다. 최솟값: 1 최댓값: 100
`data.duration_seconds`	정수	필수	kind = shot생성할 영상의 길이입니다. 단위는 초입니다. 최솟값: 1 최댓값: 60
`data.selected_image_asset_id`	문자열	선택	kind = shot영상 생성에 사용할 이미지 에셋의 id입니다. 형식: UUID (조회 응답의 id 사용)
`data.selected_video_asset_id`	문자열	선택	kind = shot최종 합성에 사용할 영상 에셋의 id입니다. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "kind": "script",
  "name": "example",
  "data": {
    "language": "example"
  }
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "content": {
      "kind": "script",
      "name": "example",
      "data": {
        "language": "example"
      }
    },
    "created_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{project_id}/resources/{resource_id}자료 하나 보기

작품 안에서 resource_id로 지정한 자료 하나의 종류·내용·revision을 조회합니다.

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`resource_id`path	문자열	필수	작품 리소스 조회 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "content": {
      "kind": "script",
      "name": "example",
      "data": {
        "language": "example"
      }
    },
    "created_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *resource_id path *

서버 응답

PATCH/api/v1/works/{project_id}/resources/{resource_id}자료 수정하기

자료의 kind와 data를 수정합니다. 다른 수정과 충돌하지 않도록 해당 자료의 최신 ETag를 If-Match로 전달하세요.

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`resource_id`path	문자열	필수	작품 리소스 조회 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`If-Match`header	문자열	필수	수정할 리소스를 먼저 조회하고, 응답 헤더의 ETag 값을 따옴표까지 그대로 넣으세요. 예: "3".

요청 본문

이름	타입	필수	설명
`kind`	문자열	필수	kind = script생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: script
`name`	문자열	필수	kind = script목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = script선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.text`	문자열	선택	kind = script대본 내용을 일반 텍스트로 입력하세요. source_asset_id를 사용하는 요청에서는 둘 중 하나만 보내세요. 최소: 1자 최대: 900000자
`data.source_asset_id`	문자열	선택	kind = script대본 원본 파일의 에셋 id입니다. 직접 입력하는 text와 둘 중 하나만 보내세요. 형식: UUID (조회 응답의 id 사용)
`data.language`	문자열	필수	kind = script대본의 언어 코드입니다. 예: ko(한국어), en(영어). 최소: 2자 최대: 16자
`kind`	문자열	필수	kind = character생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: character
`name`	문자열	필수	kind = character목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = character선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = character대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = character이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = scene생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: scene
`name`	문자열	필수	kind = scene목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = scene선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = scene대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = scene이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = prop생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: prop
`name`	문자열	필수	kind = prop목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = prop선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.description`	문자열	필수	kind = prop대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.reference_asset_ids`	목록	선택	kind = prop이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 8개
`kind`	문자열	필수	kind = episode생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: episode
`name`	문자열	필수	kind = episode목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = episode선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.script_resource_id`	문자열	필수	kind = episode이 에피소드가 사용할 대본 리소스의 id입니다. 형식: UUID (조회 응답의 id 사용)
`data.sequence`	정수	필수	kind = episode같은 목록 안에서 배치할 순서입니다. 1부터 시작합니다. 최솟값: 1 최댓값: 100
`data.raw_content`	문자열	선택	kind = episode해당 에피소드에 속하는 대본 원문입니다. 최대: 20000자
`data.description`	문자열	선택	kind = episode대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`kind`	문자열	필수	kind = shot생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 고정값: shot
`name`	문자열	필수	kind = shot목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`data`	객체	필수	kind = shot선택한 kind에 맞는 세부 입력값입니다. 아래에서 같은 종류로 표시된 필드만 보내세요.
`data.episode_id`	문자열	필수	kind = shot대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`data.scene_id`	문자열	선택	kind = shot대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`data.character_ids`	목록	선택	kind = shot샷에 등장하는 캐릭터 리소스의 id 목록입니다. 생략 시: [] 최대: 8개
`data.prop_ids`	목록	선택	kind = shot샷에서 사용하는 소품 리소스의 id 목록입니다. 생략 시: [] 최대: 8개
`data.description`	문자열	필수	kind = shot대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`data.video_prompt`	선택형	선택	kind = shot이 씬의 영상에 필요한 움직임, 카메라 동작과 연출을 적으세요.
`data.sequence`	정수	선택	kind = shot같은 목록 안에서 배치할 순서입니다. 1부터 시작합니다. 최솟값: 1 최댓값: 100
`data.duration_seconds`	정수	필수	kind = shot생성할 영상의 길이입니다. 단위는 초입니다. 최솟값: 1 최댓값: 60
`data.selected_image_asset_id`	문자열	선택	kind = shot영상 생성에 사용할 이미지 에셋의 id입니다. 형식: UUID (조회 응답의 id 사용)
`data.selected_video_asset_id`	문자열	선택	kind = shot최종 합성에 사용할 영상 에셋의 id입니다. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "kind": "script",
  "name": "example",
  "data": {
    "language": "example"
  }
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "content": {
      "kind": "script",
      "name": "example",
      "data": {
        "language": "example"
      }
    },
    "created_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *resource_id path *If-Match header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{project_id}/workflow스튜디오 제작 데이터 조회

작품의 대본·에피소드·캐릭터·씬·소품·그리드·스토리보드 장면·자산·테이크·컷 선택과 최신 revision을 한 번에 조회합니다.

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "api_runs": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "state": "example",
        "created_at": "example",
        "completed_at": "example",
        "total_steps": 0,
        "completed_steps": 0,
        "error_code": "example"
      }
    ],
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example",
    "trash": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "entity_type": "asset",
        "name": "example",
        "deleted_at": "example"
      }
    ],
    "assets": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "example",
        "kind": "example",
        "media_type": "example",
        "status": "example",
        "mime": "example",
        "lineage_id": "11111111-1111-4111-8111-111111111111",
        "version": 1,
        "is_current_version": false
      }
    ],
    "settings": {
      "title": "example",
      "tags": [
        "example"
      ],
      "cover": "example",
      "aspect": "example",
      "resolution": "example",
      "style": "example",
      "style_prompt": "example",
      "state": "example"
    },
    "script": {
      "text": "example",
      "logline": "example",
      "synopsis": "example"
    },
    "episodes": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "number": 1,
        "title": "example",
        "raw_content": "example",
        "description": "example"
      }
    ],
    "designs": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "character",
        "name": "example",
        "description": "example",
        "tags": [
          "example"
        ],
        "primary_asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "scenes": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "episode_id": "11111111-1111-4111-8111-111111111111",
        "number": 1,
        "heading": "example",
        "description": "example",
        "video_prompt": "example"
      }
    ],
    "scene_designs": [
      {
        "scene_id": "11111111-1111-4111-8111-111111111111",
        "design_id": "11111111-1111-4111-8111-111111111111",
        "kind": "example",
        "position": 1
      }
    ],
    "takes": [
      {
        "scene_id": "11111111-1111-4111-8111-111111111111",
        "asset_id": "11111111-1111-4111-8111-111111111111",
        "position": 1
      }
    ],
    "cut_selections": [
      {
        "scene_id": "11111111-1111-4111-8111-111111111111",
        "asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "design_assets": [
      {
        "design_id": "11111111-1111-4111-8111-111111111111",
        "asset_id": "11111111-1111-4111-8111-111111111111",
        "kind": "example",
        "name": "example",
        "position": 1
      }
    ]
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *

서버 응답

POST/api/v1/works/{project_id}/script/analyses스튜디오 대본 분석

작품 대본을 분석해 제작에 필요한 구조를 추출합니다. script_text를 보내면 대본을 갱신한 뒤 분석하고, 생략하면 저장된 대본을 사용합니다. 반환된 작업은 getJob으로 조회하세요.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 최소: 1자 최대: 200자
`script_text`	문자열	선택	분석할 대본 내용입니다. 생략하면 저장된 대본을 사용합니다. 최소: 1자 최대: 5000000자

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/script/builds작품 빌드

UI의 ‘작품 빌드’와 같은 기능입니다. 검증된 script_asset_ids와 revision으로 업로드한 대본을 읽어 작품 개요·에피소드·씬·캐릭터·소품·스토리보드를 구성합니다. 대본 업로드만으로 실행되지 않으며 별도로 요청해야 합니다. full_rebuild는 기존 구성을 교체하므로 직접 편집한 내용이 덮어써질 수 있습니다. 이미지와 영상은 별도로 생성합니다. UI와 같은 가격표로 AI가 반환한 실제 입력·출력 토큰을 정산합니다. 요청별 크레딧 한도는 지정하지 않습니다. GET /jobs/{job_id} → output_asset_ids.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 최소: 1자 최대: 200자
`script_asset_ids`	목록	선택	대본 구성에 사용할 자료 에셋의 id 목록입니다. 자료 라이브러리에서 확인하세요. 생략 시: []
`material_scope`	문자열	선택	unclassified는 미분류 자료, all은 전체 자료를 대본 구성 대상으로 사용합니다. 허용값: unclassified, all 생략 시: "unclassified"
`preprocess`	객체	선택	대본 구성 전에 자료에서 불필요한 내용을 걸러내는 옵션입니다.
`preprocess.ignoreAttachments`	참/거짓	선택	true이면 첨부 자료 관련 내용을 전처리에서 제외합니다. 생략 시: true
`preprocess.discardKeywords`	목록	선택	자료 정리 시 제외할 내용을 찾는 키워드 목록입니다. 생략 시: ["提示词","prompt","Midjourney","Stable Diffusion","DALL-E","Image1","Image2","正向提示词","负向提示词","视觉描述","出图要求","技术规格","画面描述","镜头提示词","请生成","角色三视图","服装本体展示","局部材质与细节放大"] 최대: 100개
`preprocess.keepLabels`	목록	선택	자료 정리 시 보존할 항목의 라벨 목록입니다. 생략 시: ["资产名称","资产ID","资产版本","关联角色资产名称","关联角色资产ID","关联场景资产名称","关联场景资产ID","关联道具资产名称","关联道具资产ID","服装变体ID","服装名称","道具资产ID","道具名称","场景资产ID","场景名称","宫格图ID","集数","主题","场景","角色名称","用途"] 최대: 100개
`rebuild_policy`	문자열	필수	full_rebuild를 지정하면 전체 재구성을 요청합니다. 실행 전에 기존 구성과 비용을 확인하세요. 고정값: full_rebuild

첫 번째 요청 · JSON

{
  "revision": 1,
  "rebuild_policy": "full_rebuild"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{project_id}/library공용 라이브러리 자료 조회

작품으로 가져올 수 있는 자료를 조회합니다. scope=personal은 본인 개인 자료실, 기본값인 scope=studio는 제작사 공용 자료실을 조회합니다.

필요 권한: assets:read

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`limit`	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 최솟값: 1 최댓값: 100
`cursor`	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요.
`scope`	문자열	선택	조회할 자료 범위를 선택합니다. 아래 허용값을 확인하세요. 허용값: studio, personal

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "example",
        "kind": "example",
        "media_type": "example",
        "mime": "example",
        "version": 1,
        "is_current_version": false
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *limit cursor scope

서버 응답

POST/api/v1/works/{project_id}/imports자료를 작품에 가져오기

asset_id로 지정한 개인·공용 자료를 작품 소유 사본으로 복사하고 사본 정보를 반환합니다. 이후 원본이 수정되거나 삭제돼도 사본은 유지됩니다.

필요 권한: assets:write, assets:read, projects:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1,
  "asset_id": "11111111-1111-4111-8111-111111111111"
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "state": "pending",
    "mime_type": "example",
    "size_bytes": 0,
    "download_url": "example",
    "expires_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/script/drafts대본 초안 생성

instructions, 선택적인 source_text, revision, max_output_tokens를 전달합니다. 기존 대본을 덮어쓰지 않고 새 대본 자료로 저장합니다. UI와 같은 가격표로 AI가 반환한 실제 입력·출력 토큰을 정산합니다. 요청별 크레딧 한도는 지정하지 않습니다. GET /jobs/{job_id} → output_asset_ids.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 최소: 1자 최대: 200자
`instructions`	문자열	필수	작성할 대본의 주제, 길이, 분위기와 반드시 포함할 내용을 적으세요. 최소: 1자 최대: 8000자
`source_text`	문자열	선택	대본 초안 작성 시 참고할 원문입니다. 최대: 50000자
`max_output_tokens`	정수	선택	생성할 대본 초안의 최대 출력 토큰 수입니다. 글자 수와는 다르며 길이와 비용에 영향을 줍니다. 생략 시: 2048 최솟값: 256 최댓값: 8192

첫 번째 요청 · JSON

{
  "revision": 1,
  "instructions": "example"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/characters캐릭터 · 조회 (list)

캐릭터 · 조회 (list). GET /api/v1/works/{work_id}/characters. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "character",
        "name": "example",
        "description": "example",
        "tags": [
          "example"
        ],
        "primary_asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/characters캐릭터 · 등록

캐릭터 · 등록. POST /api/v1/works/{work_id}/characters. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/characters/{reference_id}캐릭터 · 조회

캐릭터 · 조회. GET /api/v1/works/{work_id}/characters/{reference_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "character",
    "name": "example",
    "description": "example",
    "tags": [
      "example"
    ],
    "primary_asset_id": "11111111-1111-4111-8111-111111111111"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/characters/{reference_id}캐릭터 · 수정

캐릭터 · 수정. PATCH /api/v1/works/{work_id}/characters/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/characters/{reference_id}캐릭터 · 삭제

캐릭터 · 삭제. DELETE /api/v1/works/{work_id}/characters/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/characters/{reference_id}/primary-image캐릭터 · 참조 이미지 설정

캐릭터 · 참조 이미지 설정. PUT /api/v1/works/{work_id}/characters/{reference_id}/primary-image. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`current_asset_id`	선택형	필수	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "asset_id": "11111111-1111-4111-8111-111111111111",
  "current_asset_id": "11111111-1111-4111-8111-111111111111",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/characters/{reference_id}/image-generations캐릭터 · 참조 이미지 생성

캐릭터 · 참조 이미지 생성. POST /api/v1/works/{work_id}/characters/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`variants`	정수	선택	생성할 이미지 개수입니다. 생략 시: 1 최솟값: 1 최댓값: 4
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "image-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 20000자
`aspect_ratio`	문자열	선택	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요.
`image_size`	문자열	선택	이미지 출력 크기입니다. 선택한 모델이 지원하는 크기를 지정하세요. 최대: 40자
`quality`	문자열	선택	이미지 품질입니다. low: 낮음, medium: 보통, high: 높음. 허용값: low, medium, high
`background`	문자열	선택	이미지 배경입니다. auto: 자동, opaque: 불투명, transparent: 투명. 허용값: auto, opaque, transparent
`output_format`	문자열	선택	저장할 이미지 형식입니다. png 또는 jpeg를 선택하세요. 허용값: png, jpeg
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 16개
`slot`	문자열	선택	primary는 대표 이미지, variant는 변형 이미지로 저장합니다. 허용값: primary, variant 생략 시: "primary"
`variant_name`	문자열	선택	생성할 변형 이미지의 구분 이름입니다. 예: 겨울 의상. 최소: 1자 최대: 80자
`current_asset_id`	문자열	선택	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}캐릭터 · 씬에 연결

캐릭터 · 씬에 연결. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}캐릭터 · 씬에서 연결 해제

캐릭터 · 씬에서 연결 해제. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/background-scenes배경 씬 · 조회 (list)

배경 씬 · 조회 (list). GET /api/v1/works/{work_id}/background-scenes. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "character",
        "name": "example",
        "description": "example",
        "tags": [
          "example"
        ],
        "primary_asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/background-scenes배경 씬 · 등록

배경 씬 · 등록. POST /api/v1/works/{work_id}/background-scenes. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/background-scenes/{reference_id}배경 씬 · 조회

배경 씬 · 조회. GET /api/v1/works/{work_id}/background-scenes/{reference_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "character",
    "name": "example",
    "description": "example",
    "tags": [
      "example"
    ],
    "primary_asset_id": "11111111-1111-4111-8111-111111111111"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/background-scenes/{reference_id}배경 씬 · 수정

배경 씬 · 수정. PATCH /api/v1/works/{work_id}/background-scenes/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/background-scenes/{reference_id}배경 씬 · 삭제

배경 씬 · 삭제. DELETE /api/v1/works/{work_id}/background-scenes/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/background-scenes/{reference_id}/primary-image배경 씬 · 참조 이미지 설정

배경 씬 · 참조 이미지 설정. PUT /api/v1/works/{work_id}/background-scenes/{reference_id}/primary-image. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`current_asset_id`	선택형	필수	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "asset_id": "11111111-1111-4111-8111-111111111111",
  "current_asset_id": "11111111-1111-4111-8111-111111111111",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/background-scenes/{reference_id}/image-generations배경 씬 · 참조 이미지 생성

배경 씬 · 참조 이미지 생성. POST /api/v1/works/{work_id}/background-scenes/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`variants`	정수	선택	생성할 이미지 개수입니다. 생략 시: 1 최솟값: 1 최댓값: 4
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "image-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 20000자
`aspect_ratio`	문자열	선택	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요.
`image_size`	문자열	선택	이미지 출력 크기입니다. 선택한 모델이 지원하는 크기를 지정하세요. 최대: 40자
`quality`	문자열	선택	이미지 품질입니다. low: 낮음, medium: 보통, high: 높음. 허용값: low, medium, high
`background`	문자열	선택	이미지 배경입니다. auto: 자동, opaque: 불투명, transparent: 투명. 허용값: auto, opaque, transparent
`output_format`	문자열	선택	저장할 이미지 형식입니다. png 또는 jpeg를 선택하세요. 허용값: png, jpeg
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 16개
`slot`	문자열	선택	primary는 대표 이미지, variant는 변형 이미지로 저장합니다. 허용값: primary, variant 생략 시: "primary"
`variant_name`	문자열	선택	생성할 변형 이미지의 구분 이름입니다. 예: 겨울 의상. 최소: 1자 최대: 80자
`current_asset_id`	문자열	선택	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}배경 씬 · 씬에 연결

배경 씬 · 씬에 연결. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}배경 씬 · 씬에서 연결 해제

배경 씬 · 씬에서 연결 해제. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/props소품 · 조회 (list)

소품 · 조회 (list). GET /api/v1/works/{work_id}/props. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "character",
        "name": "example",
        "description": "example",
        "tags": [
          "example"
        ],
        "primary_asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/props소품 · 등록

소품 · 등록. POST /api/v1/works/{work_id}/props. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/props/{reference_id}소품 · 조회

소품 · 조회. GET /api/v1/works/{work_id}/props/{reference_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "character",
    "name": "example",
    "description": "example",
    "tags": [
      "example"
    ],
    "primary_asset_id": "11111111-1111-4111-8111-111111111111"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/props/{reference_id}소품 · 수정

소품 · 수정. PATCH /api/v1/works/{work_id}/props/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/props/{reference_id}소품 · 삭제

소품 · 삭제. DELETE /api/v1/works/{work_id}/props/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/props/{reference_id}/primary-image소품 · 참조 이미지 설정

소품 · 참조 이미지 설정. PUT /api/v1/works/{work_id}/props/{reference_id}/primary-image. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`current_asset_id`	선택형	필수	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "asset_id": "11111111-1111-4111-8111-111111111111",
  "current_asset_id": "11111111-1111-4111-8111-111111111111",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/props/{reference_id}/image-generations소품 · 참조 이미지 생성

소품 · 참조 이미지 생성. POST /api/v1/works/{work_id}/props/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`variants`	정수	선택	생성할 이미지 개수입니다. 생략 시: 1 최솟값: 1 최댓값: 4
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "image-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 20000자
`aspect_ratio`	문자열	선택	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요.
`image_size`	문자열	선택	이미지 출력 크기입니다. 선택한 모델이 지원하는 크기를 지정하세요. 최대: 40자
`quality`	문자열	선택	이미지 품질입니다. low: 낮음, medium: 보통, high: 높음. 허용값: low, medium, high
`background`	문자열	선택	이미지 배경입니다. auto: 자동, opaque: 불투명, transparent: 투명. 허용값: auto, opaque, transparent
`output_format`	문자열	선택	저장할 이미지 형식입니다. png 또는 jpeg를 선택하세요. 허용값: png, jpeg
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 16개
`slot`	문자열	선택	primary는 대표 이미지, variant는 변형 이미지로 저장합니다. 허용값: primary, variant 생략 시: "primary"
`variant_name`	문자열	선택	생성할 변형 이미지의 구분 이름입니다. 예: 겨울 의상. 최소: 1자 최대: 80자
`current_asset_id`	문자열	선택	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}소품 · 씬에 연결

소품 · 씬에 연결. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}소품 · 씬에서 연결 해제

소품 · 씬에서 연결 해제. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/grids그리드 · 조회 (list)

그리드 · 조회 (list). GET /api/v1/works/{work_id}/grids. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "kind": "character",
        "name": "example",
        "description": "example",
        "tags": [
          "example"
        ],
        "primary_asset_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/grids그리드 · 등록

그리드 · 등록. POST /api/v1/works/{work_id}/grids. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/grids/{reference_id}그리드 · 조회

그리드 · 조회. GET /api/v1/works/{work_id}/grids/{reference_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "character",
    "name": "example",
    "description": "example",
    "tags": [
      "example"
    ],
    "primary_asset_id": "11111111-1111-4111-8111-111111111111"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/grids/{reference_id}그리드 · 수정

그리드 · 수정. PATCH /api/v1/works/{work_id}/grids/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`name`	문자열	필수	목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`tags`	목록	선택	검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "name": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/grids/{reference_id}그리드 · 삭제

그리드 · 삭제. DELETE /api/v1/works/{work_id}/grids/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/grids/{reference_id}/primary-image그리드 · 참조 이미지 설정

그리드 · 참조 이미지 설정. PUT /api/v1/works/{work_id}/grids/{reference_id}/primary-image. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`current_asset_id`	선택형	필수	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "asset_id": "11111111-1111-4111-8111-111111111111",
  "current_asset_id": "11111111-1111-4111-8111-111111111111",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/grids/{reference_id}/image-generations그리드 · 참조 이미지 생성

그리드 · 참조 이미지 생성. POST /api/v1/works/{work_id}/grids/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`variants`	정수	선택	생성할 이미지 개수입니다. 생략 시: 1 최솟값: 1 최댓값: 4
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "image-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 20000자
`aspect_ratio`	문자열	선택	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요.
`image_size`	문자열	선택	이미지 출력 크기입니다. 선택한 모델이 지원하는 크기를 지정하세요. 최대: 40자
`quality`	문자열	선택	이미지 품질입니다. low: 낮음, medium: 보통, high: 높음. 허용값: low, medium, high
`background`	문자열	선택	이미지 배경입니다. auto: 자동, opaque: 불투명, transparent: 투명. 허용값: auto, opaque, transparent
`output_format`	문자열	선택	저장할 이미지 형식입니다. png 또는 jpeg를 선택하세요. 허용값: png, jpeg
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 16개
`slot`	문자열	선택	primary는 대표 이미지, variant는 변형 이미지로 저장합니다. 허용값: primary, variant 생략 시: "primary"
`variant_name`	문자열	선택	생성할 변형 이미지의 구분 이름입니다. 예: 겨울 의상. 최소: 1자 최대: 80자
`current_asset_id`	문자열	선택	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}그리드 · 씬에 연결

그리드 · 씬에 연결. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}그리드 · 씬에서 연결 해제

그리드 · 씬에서 연결 해제. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`reference_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *reference_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/episodes에피소드 · 조회 (list)

에피소드 · 조회 (list). GET /api/v1/works/{work_id}/episodes. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "number": 1,
        "title": "example",
        "raw_content": "example",
        "description": "example"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/episodes에피소드 생성

에피소드 생성. POST /api/v1/works/{work_id}/episodes. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`title`	문자열	필수	화면에 표시할 작품 또는 에피소드 제목입니다. 최소: 1자 최대: 200자
`number`	정수	선택	에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`raw_content`	문자열	선택	해당 에피소드에 속하는 대본 원문입니다. 최대: 20000자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "title": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/episodes/{episode_id}에피소드 · 조회

에피소드 · 조회. GET /api/v1/works/{work_id}/episodes/{episode_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "number": 1,
    "title": "example",
    "raw_content": "example",
    "description": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/episodes/{episode_id}에피소드 · 수정

에피소드 · 수정. PATCH /api/v1/works/{work_id}/episodes/{episode_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`title`	문자열	필수	화면에 표시할 작품 또는 에피소드 제목입니다. 최소: 1자 최대: 200자
`number`	정수	선택	에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`raw_content`	문자열	선택	해당 에피소드에 속하는 대본 원문입니다. 최대: 20000자
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "title": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/episodes/{episode_id}에피소드 · 삭제

에피소드 · 삭제. DELETE /api/v1/works/{work_id}/episodes/{episode_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/episodes/{episode_id}/scenes씬 · 조회 (list)

씬 · 조회 (list). GET /api/v1/works/{work_id}/episodes/{episode_id}/scenes. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "episode_id": "11111111-1111-4111-8111-111111111111",
        "number": 1,
        "heading": "example",
        "description": "example",
        "video_prompt": "example"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *cursor query limit query

서버 응답

POST/api/v1/works/{work_id}/episodes/{episode_id}/scenes씬 생성

씬 생성. POST /api/v1/works/{work_id}/episodes/{episode_id}/scenes. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`heading`	문자열	필수	씬을 구분할 제목입니다. 예: 실내 카페 - 낮. 최소: 1자 최대: 200자
`number`	정수	선택	에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`video_prompt`	선택형	선택	이 씬의 영상에 필요한 움직임, 카메라 동작과 연출을 적으세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "heading": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}씬 · 조회

씬 · 조회. GET /api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}. GET

필요 권한: projects:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "episode_id": "11111111-1111-4111-8111-111111111111",
    "number": 1,
    "heading": "example",
    "description": "example",
    "video_prompt": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *scene_id path *cursor query limit query

서버 응답

PATCH/api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}씬 · 수정

씬 · 수정. PATCH /api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`heading`	문자열	필수	씬을 구분할 제목입니다. 예: 실내 카페 - 낮. 최소: 1자 최대: 200자
`number`	정수	선택	에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`description`	문자열	선택	대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`video_prompt`	선택형	선택	이 씬의 영상에 필요한 움직임, 카메라 동작과 연출을 적으세요.
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "heading": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *scene_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/archive-importsZIP 자료 가져오기

ZIP 자료 가져오기. POST /api/v1/works/{work_id}/archive-imports. 검증 완료된 ZIP asset_id와 최신 revision을 사용합니다. 원본은 유지되며 UI와 같은 이름의 자료를 갱신하는 가져오기 규칙을 적용합니다. 완료 후 imported, failed, asset_ids를 확인하세요. 가져오기 요청에는 jobs:create, assets:read, assets:write, projects:write가 필요합니다. Idempotency-Key; GET /api/v1/works/{work_id}/archive-imports/{import_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1,
  "asset_id": "11111111-1111-4111-8111-111111111111"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "progress": {
      "phase": "extracting",
      "current": 0,
      "total": 0
    },
    "imported": 0,
    "failed": 0,
    "asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

GET/api/v1/works/{work_id}/archive-imports/{import_id}ZIP 가져오기 진행 조회

ZIP 가져오기 진행 조회. GET /api/v1/works/{work_id}/archive-imports/{import_id}. 검증 완료된 ZIP asset_id와 최신 revision을 사용합니다. 원본은 유지되며 UI와 같은 이름의 자료를 갱신하는 가져오기 규칙을 적용합니다. 완료 후 imported, failed, asset_ids를 확인하세요. 가져오기 요청에는 jobs:create, assets:read, assets:write, projects:write가 필요합니다. jobs:read

필요 권한: jobs:read

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`import_id`path	문자열	필수	형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "progress": {
      "phase": "extracting",
      "current": 0,
      "total": 0
    },
    "imported": 0,
    "failed": 0,
    "asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *import_id path *

서버 응답

POST/api/v1/works/{work_id}/uploads작품 자료 묶음 업로드 준비

작품 자료 묶음 업로드 준비. POST /api/v1/works/{work_id}/uploads. Idempotency-Key + files (1–20) → PUT upload_url → POST /api/v1/uploads/{upload_id}/complete

필요 권한: assets:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`files`	목록	필수	최대: 20개
`files[].filename`	문자열	필수	확장자를 포함한 파일 이름입니다. 예: script.txt, character.png. 폴더 경로는 넣지 마세요. 최소: 1자 최대: 200자
`files[].mime_type`	문자열	필수	파일 내용에 맞는 MIME 형식입니다. 예: text/plain, image/png. 아래 허용값 중에서 선택하세요. 허용값: text/plain, text/markdown, application/vnd.openxmlformats-officedocument.wordprocessingml.document, image/png, image/jpeg, image/webp, image/avif, audio/wav, application/zip
`files[].size_bytes`	정수	필수	업로드할 원본 파일의 정확한 바이트 크기입니다. 파일별 한도는 UI와 같은 설정을 사용하며 GET /capabilities의 upload_limits에서 확인합니다. 최댓값: 1073741824
`files[].sha256`	문자열	필수	원본 파일 바이트로 계산한 SHA-256 해시입니다. 파일이 변조되지 않았는지 확인하므로 소문자 16진수 64자 전체를 넣으세요.

첫 번째 요청 · JSON

{
  "files": [
    {
      "filename": "example",
      "mime_type": "text/plain",
      "size_bytes": 1,
      "sha256": "example"
    }
  ]
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "items": [
      {
        "filename": "example",
        "ticket": {
          "id": "11111111-1111-4111-8111-111111111111",
          "asset_id": "11111111-1111-4111-8111-111111111111",
          "upload_url": "example",
          "method": "PUT",
          "content_type": "example",
          "expires_at": "2026-09-20T00:00:00Z"
        }
      }
    ]
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

DELETE/api/v1/works/{work_id}/scenes/{scene_id}씬 · 삭제

씬 · 삭제. DELETE /api/v1/works/{work_id}/scenes/{scene_id}. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/episodes/{episode_id}/scene-order씬 순서 변경

씬 순서 변경. PUT /api/v1/works/{work_id}/episodes/{episode_id}/scene-order. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`episode_id`path	문자열	필수	대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`scene_ids`	목록	필수	배치할 순서대로 나열한 씬 id 목록입니다. 최대: 500개
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "scene_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *episode_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/script대본 저장

대본 저장. PUT /api/v1/works/{work_id}/script. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`text`	문자열	필수	대본 내용을 일반 텍스트로 입력하세요. source_asset_id를 사용하는 요청에서는 둘 중 하나만 보내세요. 최대: 5000000자
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.

첫 번째 요청 · JSON

{
  "text": "example",
  "revision": 1
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/scenes/{scene_id}/video-generations씬 영상 생성

씬 영상 생성. POST /api/v1/works/{work_id}/scenes/{scene_id}/video-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`anchor_asset_id`	문자열	선택	선택 사항입니다. 생략하면 컷에 연결된 이미지를 사용하며, 이미지가 없으면 텍스트 프롬프트만으로 영상을 생성합니다. 형식: UUID (조회 응답의 id 사용)
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 최대: 12개
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "video-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 10000자
`duration_seconds`	정수	필수	생성할 영상의 길이입니다. 단위는 초입니다. 최솟값: 1 최댓값: 60
`resolution`	문자열	필수	출력 영상의 해상도입니다. 아래 허용값 중에서 선택하세요. 최소: 1자 최대: 20자
`aspect_ratio`	문자열	필수	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요. 최소: 1자 최대: 20자
`generate_audio`	참/거짓	선택	true이면 영상 생성 시 소리도 함께 생성하도록 요청합니다.

첫 번째 요청 · JSON

{
  "revision": 1,
  "duration_seconds": 1,
  "resolution": "example",
  "aspect_ratio": "example"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/works/{work_id}/scenes/{scene_id}/selected-take최종 테이크 선택

최종 테이크 선택. PUT /api/v1/works/{work_id}/scenes/{scene_id}/selected-take. revision + Idempotency-Key

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`scene_id`path	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`take_id`	선택형	필수

첫 번째 요청 · JSON

{
  "revision": 1,
  "take_id": "11111111-1111-4111-8111-111111111111"
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

work_id path *scene_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{work_id}/exports최종본 생성

최종본 생성. POST /api/v1/works/{work_id}/exports. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`work_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`allow_partial`	참/거짓	선택	true이면 사용 가능한 영상만으로 합성합니다. false이면 필요한 영상이 모두 준비되어야 합니다. 생략 시: true
`selections`	목록	선택	최대: 200개
`selections[].scene_id`	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`selections[].asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

work_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

?? ??? API

POST/api/v1/works/{project_id}/plans제작 계획과 예상 크레딧 확인

실제 제작을 시작하지 않고, 무엇을 만들지와 예상 크레딧만 먼저 확인합니다.

필요 권한: runs:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`template_id`	문자열	필수	사용할 제작 템플릿입니다. 아래에 지정된 고정값을 넣으세요. 고정값: episode-production
`template_version`	숫자	필수	사용할 제작 템플릿의 버전 번호입니다. 고정값: 1
`project_revision`	정수	필수	작품 조회 응답의 최신 revision 숫자입니다. 요청 직전에 확인하세요.
`episode_ids`	목록	필수	제작할 에피소드의 id 목록입니다. 같은 id를 중복해서 넣지 마세요. 최대: 10개
`mode`	문자열	필수	reviewed는 중간 결과를 검토한 뒤 진행하고, automatic은 자동으로 진행합니다. 허용값: reviewed, automatic
`output_profile`	문자열	필수	제작 결과의 출력 프로필입니다. 실행 환경에 맞는 허용값을 선택하세요. 허용값: sandbox-episode-v1, episode-standard-v1

첫 번째 요청 · JSON

{
  "template_id": "episode-production",
  "template_version": 1,
  "project_revision": 1,
  "episode_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "mode": "reviewed",
  "output_profile": "sandbox-episode-v1"
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "project_revision": 1,
    "template_id": "example",
    "template_version": 1,
    "executable": false,
    "expires_at": "2026-09-20T00:00:00Z",
    "budget_ceiling": {
      "currency": "example",
      "micro_units": "example"
    },
    "steps": [
      {
        "stage_key": "example",
        "target_ids": [
          "11111111-1111-4111-8111-111111111111"
        ],
        "depends_on": [
          "example"
        ],
        "requires_review": false,
        "max_cost": {
          "currency": "example",
          "micro_units": "example"
        }
      }
    ],
    "unsupported_reasons": [
      "example"
    ]
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/runs제작 시작하기

미리 만든 plan_id의 제작 계획을 실행하고 실행 ID를 반환합니다. getRun으로 진행 상태와 결과를 확인하세요.

필요 권한: runs:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`plan_id`	문자열	필수	제작 계획 생성 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`client_reference`	문자열	선택	사용자 시스템에서 이 요청을 찾기 위한 관리번호입니다. 예: order-1234. 중복 실행 방지용 키와는 별개입니다. 최대: 128자

첫 번째 요청 · JSON

{
  "plan_id": "11111111-1111-4111-8111-111111111111"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "plan_id": "11111111-1111-4111-8111-111111111111",
    "version": 1,
    "state": "queued",
    "client_reference": "example",
    "created_at": "2026-09-20T00:00:00Z",
    "completed_at": "2026-09-20T00:00:00Z",
    "budget_remaining": {
      "currency": "example",
      "micro_units": "example"
    },
    "committed_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "unresolved_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ]
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/workflow/commands스튜디오 제작 편집

대본·스토리보드 장면·캐릭터·씬·소품·그리드·테이크 선택 등 작품의 제작 정보를 편집합니다. operation으로 할 일을 고르고 해당 input과 최신 revision을 전달하세요.

필요 권한: projects:write

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	operation = design.asset.set최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.asset.set실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.asset.set
`input`	객체	필수	operation = design.asset.set선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.asset.set처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	문자열	필수	operation = design.asset.set사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.kind`	문자열	필수	operation = design.asset.set생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 허용값: primary, variant
`input.current_asset_id`	선택형	필수	operation = design.asset.set현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요.
`input.name`	문자열	선택	operation = design.asset.set목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`revision`	정수	필수	operation = asset.delete최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = asset.delete실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: asset.delete
`input`	객체	필수	operation = asset.delete선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = asset.delete처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = trash.restore최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = trash.restore실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: trash.restore
`input`	객체	필수	operation = trash.restore선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = trash.restore처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.entity_type`	문자열	필수	operation = trash.restore복원할 휴지통 항목의 종류입니다. asset은 파일, design은 캐릭터·씬·소품·그리드 항목입니다. 허용값: asset, design
`revision`	정수	필수	operation = scene.duplicate최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.duplicate실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.duplicate
`input`	객체	필수	operation = scene.duplicate선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = scene.duplicate처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = project.settings.update최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = project.settings.update실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: project.settings.update
`input`	객체	필수	operation = project.settings.update선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.title`	문자열	필수	operation = project.settings.update화면에 표시할 작품 또는 에피소드 제목입니다. 최소: 1자 최대: 120자
`input.tags`	목록	필수	operation = project.settings.update검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`input.cover`	문자열	필수	operation = project.settings.update작품 표지 스타일입니다. 아래 허용값 중에서 선택하세요. 허용값: amber, indigo, teal, rust, moss, ink, sage, bone, wine, wash, blush, void
`input.aspect`	문자열	필수	operation = project.settings.update작품 화면의 가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 허용값: 16:9, 9:16, 1:1, 4:3, 21:9
`input.resolution`	문자열	필수	operation = project.settings.update출력 영상의 해상도입니다. 아래 허용값 중에서 선택하세요. 허용값: 480p, 720p, 1080p, 2k
`input.style`	문자열	필수	operation = project.settings.update작품에 적용할 시각 스타일의 id입니다. 아래 허용값 중에서 선택하세요. 허용값: realistic_general, realistic_urban, realistic_cinematic, 2d_japanese_manga, 2d_korean_urban, 2d_korean, 2d_otome, 2d_chinese_manga, 2d_classical, 3d_chinese, 3d_xianxia, 3d_cartoon, cg_general, cg_cyberpunk, ink_gongbi, custom
`input.style_prompt`	문자열	필수	operation = project.settings.update기본 스타일에 추가할 색감, 질감, 분위기 등의 지시사항입니다. 최대: 1000자
`revision`	정수	필수	operation = project.rename최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = project.rename실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: project.rename
`input`	객체	필수	operation = project.rename선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.title`	문자열	필수	operation = project.rename화면에 표시할 작품 또는 에피소드 제목입니다. 최소: 1자 최대: 120자
`revision`	정수	필수	operation = project.state.set최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = project.state.set실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: project.state.set
`input`	객체	필수	operation = project.state.set선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.state`	문자열	필수	operation = project.state.set작품 상태입니다. active는 사용 중, archived는 보관 상태입니다. 허용값: active, archived
`revision`	정수	필수	operation = script.update최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = script.update실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: script.update
`input`	객체	필수	operation = script.update선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.text`	문자열	필수	operation = script.update대본 내용을 일반 텍스트로 입력하세요. source_asset_id를 사용하는 요청에서는 둘 중 하나만 보내세요. 최대: 5000000자
`revision`	정수	필수	operation = script.bible.update최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = script.bible.update실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: script.bible.update
`input`	객체	필수	operation = script.bible.update선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.logline`	문자열	필수	operation = script.bible.update이야기의 핵심을 한 문장으로 요약하세요. 최대: 500자
`input.synopsis`	문자열	필수	operation = script.bible.update이야기의 주요 사건과 흐름을 요약하세요. 최대: 4000자
`revision`	정수	필수	operation = episode.save최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = episode.save실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: episode.save
`input`	객체	필수	operation = episode.save선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	선택	operation = episode.save처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.title`	문자열	필수	operation = episode.save화면에 표시할 작품 또는 에피소드 제목입니다. 최소: 1자 최대: 200자
`input.number`	정수	선택	operation = episode.save에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`input.raw_content`	문자열	선택	operation = episode.save해당 에피소드에 속하는 대본 원문입니다. 최대: 20000자
`input.description`	문자열	선택	operation = episode.save대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`revision`	정수	필수	operation = episode.delete최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = episode.delete실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: episode.delete
`input`	객체	필수	operation = episode.delete선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = episode.delete처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = scene.save최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.save실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.save
`input`	객체	필수	operation = scene.save선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	선택	operation = scene.save처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.episode_id`	문자열	필수	operation = scene.save대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.heading`	문자열	필수	operation = scene.save씬을 구분할 제목입니다. 예: 실내 카페 - 낮. 최소: 1자 최대: 200자
`input.number`	정수	선택	operation = scene.save에피소드 또는 씬의 표시 번호입니다. 1부터 시작합니다.
`input.description`	문자열	선택	operation = scene.save대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`input.video_prompt`	선택형	선택	operation = scene.save이 씬의 영상에 필요한 움직임, 카메라 동작과 연출을 적으세요.
`revision`	정수	필수	operation = scene.delete최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.delete실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.delete
`input`	객체	필수	operation = scene.delete선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = scene.delete처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = scene.reorder최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.reorder실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.reorder
`input`	객체	필수	operation = scene.reorder선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.episode_id`	문자열	필수	operation = scene.reorder대상 에피소드의 id입니다. 작품의 에피소드 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.scene_ids`	목록	필수	operation = scene.reorder배치할 순서대로 나열한 씬 id 목록입니다. 최대: 500개
`revision`	정수	필수	operation = design.save최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.save실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.save
`input`	객체	필수	operation = design.save선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	선택	operation = design.save처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.kind`	문자열	필수	operation = design.save생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 허용값: character, scene, prop, grid
`input.name`	문자열	필수	operation = design.save목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 200자
`input.description`	문자열	선택	operation = design.save대상의 모습, 내용 또는 연출 의도를 구체적으로 적으세요. 최대: 4000자
`input.tags`	목록	선택	operation = design.save검색과 분류에 사용할 짧은 태그 목록입니다. 최대: 8개
`revision`	정수	필수	operation = design.delete최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.delete실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.delete
`input`	객체	필수	operation = design.delete선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.delete처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = design.voice.set최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.voice.set실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.voice.set
`input`	객체	필수	operation = design.voice.set선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.voice.set처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	선택형	필수	operation = design.voice.set사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요.
`revision`	정수	필수	operation = design.asset.detach최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.asset.detach실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.asset.detach
`input`	객체	필수	operation = design.asset.detach선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.asset.detach처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	문자열	필수	operation = design.asset.detach사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.kind`	문자열	필수	operation = design.asset.detach생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 허용값: primary, variant, voice
`revision`	정수	필수	operation = design.asset.restore최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.asset.restore실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.asset.restore
`input`	객체	필수	operation = design.asset.restore선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.asset.restore처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.current_asset_id`	문자열	필수	operation = design.asset.restore현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)
`input.restore_asset_id`	문자열	필수	operation = design.asset.restore이전 버전으로 복원할 에셋의 id입니다. 형식: UUID (조회 응답의 id 사용)
`input.kind`	문자열	필수	operation = design.asset.restore생성하거나 처리할 대상의 종류입니다. 아래 허용값 중에서 선택하세요. 허용값: primary, variant
`revision`	정수	필수	operation = design.variant.rename최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = design.variant.rename실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: design.variant.rename
`input`	객체	필수	operation = design.variant.rename선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.id`	문자열	필수	operation = design.variant.rename처리할 항목의 id입니다. 해당 항목의 조회 응답에서 복사하세요. 새 항목을 만드는 요청에서 선택 항목이면 생략할 수 있습니다. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	문자열	필수	operation = design.variant.rename사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.name`	문자열	필수	operation = design.variant.rename목록에 표시할 이름입니다. 사용자가 구분하기 쉬운 이름을 입력하세요. 최소: 1자 최대: 80자
`revision`	정수	필수	operation = scene.design.attach최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.design.attach실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.design.attach
`input`	객체	필수	operation = scene.design.attach선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.scene_id`	문자열	필수	operation = scene.design.attach대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.design_id`	문자열	필수	operation = scene.design.attach대상 캐릭터·씬·소품·그리드 항목의 id입니다. Studio 작품 조회 응답의 designs에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = scene.design.detach최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = scene.design.detach실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: scene.design.detach
`input`	객체	필수	operation = scene.design.detach선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.scene_id`	문자열	필수	operation = scene.design.detach대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.design_id`	문자열	필수	operation = scene.design.detach대상 캐릭터·씬·소품·그리드 항목의 id입니다. Studio 작품 조회 응답의 designs에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`revision`	정수	필수	operation = cut.take.select최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = cut.take.select실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: cut.take.select
`input`	객체	필수	operation = cut.take.select선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.scene_id`	문자열	필수	operation = cut.take.select대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	선택형	필수	operation = cut.take.select사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요.
`revision`	정수	필수	operation = take.delete최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`operation`	문자열	필수	operation = take.delete실행할 편집 작업입니다. 예: project.rename은 제목 수정, scene.save는 씬 저장입니다. 선택한 작업에 맞는 input을 보내세요. 고정값: take.delete
`input`	객체	필수	operation = take.delete선택한 operation에 필요한 입력값입니다. 아래에서 같은 작업으로 표시된 필드만 보내세요.
`input.scene_id`	문자열	필수	operation = take.delete대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`input.asset_id`	문자열	필수	operation = take.delete사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1,
  "operation": "design.asset.set",
  "input": {
    "id": "11111111-1111-4111-8111-111111111111",
    "asset_id": "11111111-1111-4111-8111-111111111111",
    "kind": "primary",
    "current_asset_id": "11111111-1111-4111-8111-111111111111"
  }
}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "work_id": "11111111-1111-4111-8111-111111111111",
    "changed_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "studio_url": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/cut/exports스튜디오 컷 내보내기

선택한 장면 영상을 회차·장면 순서대로 합칩니다. selections로 테이크를 직접 지정하고 allow_partial로 영상이 없는 장면을 건너뛸지 정합니다. getJob에서 완료와 결과를 확인하세요.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`allow_partial`	참/거짓	선택	true이면 사용 가능한 영상만으로 합성합니다. false이면 필요한 영상이 모두 준비되어야 합니다. 생략 시: true
`selections`	목록	선택	최대: 200개
`selections[].scene_id`	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`selections[].asset_id`	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/storyboard/videos스토리보드 장면 영상 생성

scene_id로 지정한 장면의 영상을 선택한 모델·길이·해상도로 생성합니다. anchor_asset_id로 시작 이미지를 지정할 수 있습니다. 반환된 작업은 getJob으로 조회하세요.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`scene_id`	문자열	필수	대상 씬의 id입니다. Studio 작품 조회 응답의 scenes에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`anchor_asset_id`	문자열	선택	선택 사항입니다. 생략하면 컷에 연결된 이미지를 사용하며, 이미지가 없으면 텍스트 프롬프트만으로 영상을 생성합니다. 형식: UUID (조회 응답의 id 사용)
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 최대: 12개
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "video-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 10000자
`duration_seconds`	정수	필수	생성할 영상의 길이입니다. 단위는 초입니다. 최솟값: 1 최댓값: 60
`resolution`	문자열	필수	출력 영상의 해상도입니다. 아래 허용값 중에서 선택하세요. 최소: 1자 최대: 20자
`aspect_ratio`	문자열	필수	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요. 최소: 1자 최대: 20자
`generate_audio`	참/거짓	선택	true이면 영상 생성 시 소리도 함께 생성하도록 요청합니다.

첫 번째 요청 · JSON

{
  "revision": 1,
  "scene_id": "11111111-1111-4111-8111-111111111111",
  "duration_seconds": 1,
  "resolution": "example",
  "aspect_ratio": "example"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/works/{project_id}/designs/images캐릭터·씬·소품·그리드 이미지 생성

design_id로 지정한 캐릭터·씬·소품·그리드 항목에 이미지 1~4장을 생성합니다. 프롬프트·참조 이미지를 지정하고 기본 이미지 또는 변형 슬롯을 선택할 수 있습니다. getJob에서 결과를 확인하세요.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`project_id`path	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`revision`	정수	필수	최신 작품 조회 응답의 revision 숫자입니다. 오래된 값으로 수정하면 충돌 오류가 발생합니다.
`design_id`	문자열	필수	대상 캐릭터·씬·소품·그리드 항목의 id입니다. Studio 작품 조회 응답의 designs에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`variants`	정수	선택	생성할 이미지 개수입니다. 생략 시: 1 최솟값: 1 최댓값: 4
`model`	문자열	선택	생성에 사용할 모델 등급입니다. 아래 허용값을 사용하고 GET /capabilities에서 사용 가능 여부를 확인하세요. 생략 시: "image-standard" 최소: 1자 최대: 200자
`prompt`	문자열	선택	생성할 이미지나 영상의 대상, 분위기, 구도를 구체적으로 적으세요. 최소: 1자 최대: 20000자
`aspect_ratio`	문자열	선택	가로:세로 비율입니다. 예: 16:9(가로), 9:16(세로). 모델이 지원하는 값을 사용하세요.
`image_size`	문자열	선택	이미지 출력 크기입니다. 선택한 모델이 지원하는 크기를 지정하세요. 최대: 40자
`quality`	문자열	선택	이미지 품질입니다. low: 낮음, medium: 보통, high: 높음. 허용값: low, medium, high
`background`	문자열	선택	이미지 배경입니다. auto: 자동, opaque: 불투명, transparent: 투명. 허용값: auto, opaque, transparent
`output_format`	문자열	선택	저장할 이미지 형식입니다. png 또는 jpeg를 선택하세요. 허용값: png, jpeg
`reference_asset_ids`	목록	선택	이미지 생성에 참고할 에셋 id 목록입니다. 사용하는 모델의 참조 이미지 제한도 확인하세요. 생략 시: [] 최대: 16개
`slot`	문자열	선택	primary는 대표 이미지, variant는 변형 이미지로 저장합니다. 허용값: primary, variant 생략 시: "primary"
`variant_name`	문자열	선택	생성할 변형 이미지의 구분 이름입니다. 예: 겨울 의상. 최소: 1자 최대: 80자
`current_asset_id`	문자열	선택	현재 선택된 에셋의 id입니다. 최신 작품 조회 결과를 사용하세요. 형식: UUID (조회 응답의 id 사용)

첫 번째 요청 · JSON

{
  "revision": 1,
  "design_id": "11111111-1111-4111-8111-111111111111"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

project_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

업로드

POST/api/v1/uploads파일 올릴 주소 받기

파일 정보를 등록하고 upload_url을 받습니다. 이 주소로 파일 내용을 PUT한 뒤 업로드 완료 API를 호출하세요. TXT·Markdown·DOCX·PNG·JPEG·WebP·AVIF·WAV·ZIP을 지원합니다. 파일별 바이트 한도는 UI와 같은 설정을 사용하며 GET /capabilities의 upload_limits에서 확인합니다. 대본은 최대 5,000,000자입니다. 파일명에 경로 구분자를 넣을 수 없습니다. WAV는 PCM 또는 IEEE float 형식이어야 합니다.

필요 권한: assets:write

매개변수

이름	타입	필수	설명
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`project_id`	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`filename`	문자열	필수	확장자를 포함한 파일 이름입니다. 예: script.txt, character.png. 폴더 경로는 넣지 마세요. 최소: 1자 최대: 200자
`mime_type`	문자열	필수	파일 내용에 맞는 MIME 형식입니다. 예: text/plain, image/png. 아래 허용값 중에서 선택하세요. 허용값: text/plain, text/markdown, application/vnd.openxmlformats-officedocument.wordprocessingml.document, image/png, image/jpeg, image/webp, image/avif, audio/wav, application/zip
`size_bytes`	정수	필수	업로드할 원본 파일의 정확한 바이트 크기입니다. 파일별 한도는 UI와 같은 설정을 사용하며 GET /capabilities의 upload_limits에서 확인합니다. 최댓값: 1073741824
`sha256`	문자열	필수	원본 파일 바이트로 계산한 SHA-256 해시입니다. 파일이 변조되지 않았는지 확인하므로 소문자 16진수 64자 전체를 넣으세요.

첫 번째 요청 · JSON

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "filename": "example",
  "mime_type": "text/plain",
  "size_bytes": 1,
  "sha256": "example"
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "asset_id": "11111111-1111-4111-8111-111111111111",
    "upload_url": "example",
    "method": "PUT",
    "content_type": "example",
    "expires_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

Idempotency-Key header * 요청 본문 application/json

서버 응답

POST/api/v1/uploads/{upload_id}/complete파일 다 올렸다고 알리기

전송된 파일이 등록한 파일 정보와 맞는지 검증하고, 제작에 사용할 자산 정보를 반환합니다.

필요 권한: assets:write

매개변수

이름	타입	필수	설명
`upload_id`path	문자열	필수	업로드 생성 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

첫 번째 요청 · JSON

{}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "state": "pending",
    "mime_type": "example",
    "size_bytes": 0,
    "download_url": "example",
    "expires_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

upload_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

PUT/api/v1/uploads/{upload_id}/content파일 내용 올리기

발급받은 업로드 주소에 파일 바이트를 application/octet-stream으로 전송합니다. 전송 성공 후 completeUpload를 호출하세요.

필요 권한: assets:write

매개변수

이름	타입	필수	설명
`upload_id`path	문자열	필수	업로드 생성 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "uploaded": true
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

upload_id path * application/octet-stream

서버 응답

자산·결과

GET/api/v1/assets/{asset_id}결과물 정보와 내려받기 링크 보기

자산의 파일 정보와 다운로드 가능한 경우 서명된 download_url을 조회합니다. 반환된 주소의 유효 시간 안에 파일을 받으세요.

필요 권한: assets:read

매개변수

이름	타입	필수	설명
`asset_id`path	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "state": "pending",
    "mime_type": "example",
    "size_bytes": 0,
    "download_url": "example",
    "expires_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

asset_id path *

서버 응답

GET/api/v1/downloads/{asset_id}완성된 파일 내려받기

getAsset에서 받은 서명된 download_url 전체 주소로 파일을 내려받습니다. 링크의 유효 시간은 5분입니다.

매개변수

이름	타입	필수	설명
`asset_id`path	문자열	필수	사용할 파일의 에셋 id입니다. 업로드 완료 후 또는 에셋 목록에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`expires`query	문자열	필수	서명된 다운로드 URL에 포함된 만료값입니다. 반환된 URL의 값을 변경하지 마세요.
`signature`query	문자열	필수	서명된 다운로드 URL에 포함된 인증값입니다. 반환된 URL을 그대로 사용하세요.

응답

HTTP 200 파일 바이트

application/octet-stream · 파일 바이트

오류 응답 · error.code ↗

직접 호출

asset_id path *expires query *signature query *

서버 응답

제작 실행

GET/api/v1/runs제작 목록 보기

제작 실행 목록을 조회합니다. 작품·실행 상태·client_reference·기간으로 필요한 실행을 찾을 수 있습니다.

필요 권한: runs:read

매개변수

이름	타입	필수	설명
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100
`project_id`query	문자열	선택	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`state`query	문자열	선택	작품 상태입니다. active는 사용 중, archived는 보관 상태입니다. 허용값: queued, running, awaiting_review, stopping, paused, needs_attention, partially_succeeded, succeeded, failed, cancelled
`client_reference`query	문자열	선택	사용자 시스템에서 이 요청을 찾기 위한 관리번호입니다. 예: order-1234. 중복 실행 방지용 키와는 별개입니다. 최소: 1자 최대: 128자
`from`query	문자열	선택	조회 기간의 시작 시각입니다. 시간대를 포함하세요. 예: 2026-09-21T00:00:00+09:00. 형식: 시간대를 포함한 날짜와 시각
`to`query	문자열	선택	조회 기간의 종료 시각입니다. 시간대를 포함하세요. 예: 2026-09-22T00:00:00+09:00. 형식: 시간대를 포함한 날짜와 시각

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "work_id": "11111111-1111-4111-8111-111111111111",
        "plan_id": "11111111-1111-4111-8111-111111111111",
        "version": 1,
        "state": "queued",
        "client_reference": "example",
        "created_at": "2026-09-20T00:00:00Z",
        "completed_at": "2026-09-20T00:00:00Z",
        "budget_remaining": {
          "currency": "example",
          "micro_units": "example"
        },
        "committed_cost": {
          "currency": "example",
          "micro_units": "example"
        },
        "unresolved_cost": {
          "currency": "example",
          "micro_units": "example"
        },
        "output_asset_ids": [
          "11111111-1111-4111-8111-111111111111"
        ]
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

cursor query limit query project_id query state query client_reference query from query to query

서버 응답

GET/api/v1/runs/{run_id}제작 진행 상태 보기

제작 실행의 현재 상태·버전·준비된 결과를 조회합니다. 승인·중지 같은 결정을 보낼 때 이 버전을 사용하세요.

필요 권한: runs:read

매개변수

이름	타입	필수	설명
`run_id`path	문자열	필수	실행 생성 또는 실행 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "plan_id": "11111111-1111-4111-8111-111111111111",
    "version": 1,
    "state": "queued",
    "client_reference": "example",
    "created_at": "2026-09-20T00:00:00Z",
    "completed_at": "2026-09-20T00:00:00Z",
    "budget_remaining": {
      "currency": "example",
      "micro_units": "example"
    },
    "committed_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "unresolved_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ]
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

run_id path *

서버 응답

GET/api/v1/runs/{run_id}/steps단계별 진행 상황 보기

제작 실행의 개별 단계와 상태를 조회합니다. 어느 단계가 대기·진행·완료 상태인지 확인할 수 있습니다.

필요 권한: runs:read

매개변수

이름	타입	필수	설명
`run_id`path	문자열	필수	실행 생성 또는 실행 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "run_id": "11111111-1111-4111-8111-111111111111",
        "stage_key": "example",
        "target_id": "11111111-1111-4111-8111-111111111111",
        "job_id": "11111111-1111-4111-8111-111111111111",
        "state": "blocked",
        "output_asset_ids": [
          "11111111-1111-4111-8111-111111111111"
        ],
        "error_code": "example",
        "ordinal": 1
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

run_id path *cursor query limit query

서버 응답

GET/api/v1/runs/{run_id}/events제작 중 남은 기록 보기

상태 변경·검토 요청 등 제작 실행 중 발생한 이벤트를 조회합니다. 제작이 어떤 과정을 거쳤는지 확인할 때 사용합니다.

필요 권한: runs:read

매개변수

이름	타입	필수	설명
`run_id`path	문자열	필수	실행 생성 또는 실행 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "event_id": "11111111-1111-4111-8111-111111111111",
        "run_id": "11111111-1111-4111-8111-111111111111",
        "sequence": 1,
        "type": "run.state_changed",
        "state": "queued",
        "step_id": "11111111-1111-4111-8111-111111111111",
        "created_at": "2026-09-20T00:00:00Z"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

run_id path *cursor query limit query

서버 응답

POST/api/v1/runs/{run_id}/decisions계속할지 승인하거나 멈추기

제작 실행을 승인·중지·재개하거나 남은 단계를 취소하고, 영상 결과 조회를 재개합니다. action으로 동작을 선택하고 최신 실행 버전을 expected_version으로 전달하세요. retry_result는 저장된 영상 작업의 결과 조회만 재개합니다. 최신 expected_version과 step_id를 보내세요. 기존 작업과 크레딧 예약을 유지하며 새 영상을 생성하지 않습니다. 접수 후 24시간 이내의 재조회 가능한 영상만 지원합니다. 결과·사용량이 불명확한 다른 작업은 운영자 확인이 필요합니다.

필요 권한: runs:write

매개변수

이름	타입	필수	설명
`run_id`path	문자열	필수	실행 생성 또는 실행 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`action`	문자열	필수	approve: 승인, stop: 중지, resume: 재개, cancel_remaining: 남은 작업 취소, retry_result: 기존 생성 결과 복구입니다. 허용값: approve, stop, resume, cancel_remaining, retry_result
`expected_version`	정수	필수	실행 조회 응답에서 확인한 최신 version입니다. 검토 이후 상태가 바뀌지 않았는지 확인합니다.
`step_id`	문자열	선택	복구하거나 처리할 실행 단계의 id입니다. 실행 상세 응답에서 확인하세요. 형식: UUID (조회 응답의 id 사용)
`selected_asset_ids`	목록	선택	검토 후 선택한 결과 에셋의 id 목록입니다. 최대: 10개

첫 번째 요청 · JSON

{
  "action": "approve",
  "expected_version": 1
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "plan_id": "11111111-1111-4111-8111-111111111111",
    "version": 1,
    "state": "queued",
    "client_reference": "example",
    "created_at": "2026-09-20T00:00:00Z",
    "completed_at": "2026-09-20T00:00:00Z",
    "budget_remaining": {
      "currency": "example",
      "micro_units": "example"
    },
    "committed_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "unresolved_cost": {
      "currency": "example",
      "micro_units": "example"
    },
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ]
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

run_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

워크플로 기능

GET/api/v1/jobs/{job_id}실행한 작업의 상태와 결과 보기

접수한 작업의 현재 상태와 결과 자산 ID를 조회합니다. 완료되면 getAsset으로 결과 파일을 받으세요.

필요 권한: jobs:read

매개변수

이름	타입	필수	설명
`job_id`path	문자열	필수	작업 접수 응답에서 받은 id입니다. 진행 상황 조회에 사용합니다. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

job_id path *

서버 응답

GET/api/v1/jobs/{job_id}/build작품 빌드 진행·자료 조회

작품 빌드 작업의 현재 단계·진행 메시지·원문 자료와 처리용으로 준비된 텍스트를 조회합니다.

필요 권한: jobs:read, assets:read

매개변수

이름	타입	필수	설명
`job_id`path	문자열	필수	작업 접수 응답에서 받은 id입니다. 진행 상황 조회에 사용합니다. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "state": "example",
    "stage": "example",
    "messages": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "role": "assistant",
        "stage": "example",
        "content": "example",
        "status": "streaming",
        "seq": 1,
        "created_at": "example",
        "updated_at": "example"
      }
    ],
    "sources": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "example",
        "filterMode": "prompt_index",
        "sourceText": "example",
        "llmText": "example",
        "originalChars": 1,
        "preparedChars": 1
      }
    ]
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

job_id path *

서버 응답

?? ??? API

POST/api/v1/jobs기능 하나만 바로 실행하기

전체 제작을 돌리지 않고 기능 하나만 골라 바로 실행합니다. analyze_script는 대본을 읽어 샷을 만들고, generate_image는 캐릭터·장면·소품·샷 이미지를 만듭니다. generate_video는 이미지를 고른 샷의 영상을 만들고, assemble_video는 샷 영상이 모두 준비된 에피소드를 하나로 잇습니다. 요청에는 항상 작품의 최신 revision을 넣어 주세요. Live로 보내면 크레딧을 먼저 잡아 둡니다.

필요 권한: jobs:create

매개변수

이름	타입	필수	설명
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`project_id`	문자열	필수	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`project_revision`	정수	필수	작품 조회 응답의 최신 revision 숫자입니다. 요청 직전에 확인하세요.
`target_id`	문자열	필수	작업 대상 리소스의 id입니다. 대본 분석·합성은 에피소드, 영상 생성은 샷을 지정하세요. 형식: UUID (조회 응답의 id 사용)
`type`	문자열	필수	실행할 작업 종류입니다. analyze_script: 대본 분석, generate_image: 이미지 생성, generate_video: 영상 생성, assemble_video: 영상 합성. 허용값: analyze_script, generate_image, generate_video, assemble_video
`profile_id`	문자열	필수	사용할 생성 프로필의 id입니다. GET /capabilities 응답에서 지원하는 값을 확인하세요. 최대: 100자
`client_reference`	문자열	선택	사용자 시스템에서 이 요청을 찾기 위한 관리번호입니다. 예: order-1234. 중복 실행 방지용 키와는 별개입니다. 최대: 128자

첫 번째 요청 · JSON

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "project_revision": 1,
  "target_id": "11111111-1111-4111-8111-111111111111",
  "type": "analyze_script",
  "profile_id": "example"
}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "state": "queued",
    "output_asset_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

Idempotency-Key header * 요청 본문 application/json

서버 응답

요청 로그

GET/api/v1/requests보낸 요청 기록 목록 보기

API 요청의 HTTP 상태와 처리 시간 등 호출 기록을 조회합니다. 작품·기간으로 범위를 좁혀 호출 내역을 확인할 수 있습니다.

필요 권한: requests:read

매개변수

이름	타입	필수	설명
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100
`from`query	문자열	선택	조회 기간의 시작 시각입니다. 시간대를 포함하세요. 예: 2026-09-21T00:00:00+09:00. 형식: 시간대를 포함한 날짜와 시각
`to`query	문자열	선택	조회 기간의 종료 시각입니다. 시간대를 포함하세요. 예: 2026-09-22T00:00:00+09:00. 형식: 시간대를 포함한 날짜와 시각
`project_id`query	문자열	선택	작업할 작품의 id입니다. 작품 생성 또는 목록 조회 응답에서 가져오세요. 형식: UUID (조회 응답의 id 사용)
`run_id`query	문자열	선택	실행 생성 또는 실행 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`job_id`query	문자열	선택	작업 접수 응답에서 받은 id입니다. 진행 상황 조회에 사용합니다. 형식: UUID (조회 응답의 id 사용)
`key_id`query	문자열	선택	요청 기록을 특정 API 키로 좁힐 때 사용하는 키의 id입니다. 비밀 키 문자열을 넣지 마세요. 형식: UUID (조회 응답의 id 사용)
`status_code`query	정수	선택	이 HTTP 상태 코드로 응답한 요청만 조회합니다. 예: 200, 400. 최솟값: 100 최댓값: 599
`method`query	문자열	선택	이 HTTP 메서드로 보낸 요청만 조회합니다. 예: GET, POST. 허용값: GET, POST, PATCH, PUT
`route_template`query	문자열	선택	조회할 API 경로 패턴입니다. 실제 id 대신 명세의 경로 템플릿을 넣으세요. 최소: 1자 최대: 300자

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "request_id": "11111111-1111-4111-8111-111111111111",
        "created_at": "2026-09-20T00:00:00Z",
        "method": "GET",
        "route_template": "example",
        "status_code": 100,
        "duration_ms": 0,
        "actor_kind": "api_key",
        "work_id": "11111111-1111-4111-8111-111111111111",
        "run_id": "11111111-1111-4111-8111-111111111111",
        "job_id": "11111111-1111-4111-8111-111111111111",
        "replayed": false,
        "error_code": "example"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

cursor query limit query from query to query project_id query run_id query job_id query key_id query status_code query method query route_template query

서버 응답

GET/api/v1/requests/{request_id}보낸 요청 기록 하나 보기

request_id로 API 호출 하나의 HTTP 상태·처리 시간·연결된 실행 또는 작업을 조회합니다.

필요 권한: requests:read

매개변수

이름	타입	필수	설명
`request_id`path	문자열	필수	조회할 API 요청의 request_id입니다. 응답 본문 또는 X-Request-Id 헤더에서 확인하세요. 형식: UUID (조회 응답의 id 사용)

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-20T00:00:00Z",
    "method": "GET",
    "route_template": "example",
    "status_code": 100,
    "duration_ms": 0,
    "actor_kind": "api_key",
    "work_id": "11111111-1111-4111-8111-111111111111",
    "run_id": "11111111-1111-4111-8111-111111111111",
    "job_id": "11111111-1111-4111-8111-111111111111",
    "replayed": false,
    "error_code": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

request_id path *

서버 응답

사용량

GET/api/v1/usage크레딧 사용량 보기

조회 기간의 사용량 합계를 확인합니다. 예약된 금액과 정산된 금액을 함께 조회할 수 있습니다.

필요 권한: usage:read

매개변수

매개변수 없음

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "period_start": "2026-09-20T00:00:00Z",
    "period_end": "2026-09-20T00:00:00Z",
    "as_of": "2026-09-20T00:00:00Z",
    "http_requests": 0,
    "runs": 0,
    "jobs": 0,
    "reserved": {
      "currency": "example",
      "micro_units": "example"
    },
    "committed": {
      "currency": "example",
      "micro_units": "example"
    },
    "unresolved": {
      "currency": "example",
      "micro_units": "example"
    },
    "remaining": {
      "currency": "example",
      "micro_units": "example"
    },
    "amount_basis": "partner_limit",
    "billing_mode": "pilot"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

서버 응답

Webhook

GET/api/v1/webhook-endpointsWebhook 알림 주소 목록 보기

등록된 Webhook 수신 주소와 구독 이벤트·활성 상태를 조회합니다.

필요 권한: webhooks:read

매개변수

이름	타입	필수	설명
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "url": "example",
        "work_ids": [
          "11111111-1111-4111-8111-111111111111"
        ],
        "events": [
          "run.state_changed"
        ],
        "enabled": false,
        "verified": false,
        "secret_version": 1,
        "created_at": "2026-09-20T00:00:00Z"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

cursor query limit query

서버 응답

POST/api/v1/webhook-endpointsWebhook 알림 주소 등록

지정한 작품에서 선택한 제작 이벤트가 발생하면 알림을 받을 Webhook 주소를 등록합니다.

필요 권한: webhooks:write

매개변수

이름	타입	필수	설명
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

이름	타입	필수	설명
`url`	문자열	필수	이벤트 알림을 받을 웹훅 서버의 URL입니다. 형식: uri 최대: 2000자
`project_ids`	목록	필수	대상 작품의 id 목록입니다. 작품 조회 응답의 id를 사용하세요. 최대: 100개
`events`	목록	필수	알림을 받을 이벤트 목록입니다. 아래 허용값 중 필요한 이벤트를 선택하세요. 최대: 4개

첫 번째 요청 · JSON

{
  "url": "example",
  "project_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "events": [
    "run.state_changed"
  ]
}

응답

HTTP 201 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "endpoint": {
      "id": "11111111-1111-4111-8111-111111111111",
      "url": "example",
      "work_ids": [
        "11111111-1111-4111-8111-111111111111"
      ],
      "events": [
        "run.state_changed"
      ],
      "enabled": false,
      "verified": false,
      "secret_version": 1,
      "created_at": "2026-09-20T00:00:00Z"
    }
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

Idempotency-Key header * 요청 본문 application/json

서버 응답

PATCH/api/v1/webhook-endpoints/{endpoint_id}Webhook 알림 주소 수정

Webhook의 알림 수신을 켜거나 끄고, 수신할 이벤트 종류를 변경합니다.

필요 권한: webhooks:write

매개변수

이름	타입	필수	설명
`endpoint_id`path	문자열	필수	웹훅 등록 또는 목록 응답에서 받은 id입니다. 형식: UUID (조회 응답의 id 사용)
`If-Match`header	문자열	필수	수정할 리소스를 먼저 조회하고, 응답 헤더의 ETag 값을 따옴표까지 그대로 넣으세요. 예: "3".

요청 본문

이름	타입	필수	설명
`enabled`	참/거짓	선택	true이면 웹훅 전송을 활성화하고, false이면 중지합니다.
`events`	목록	선택	알림을 받을 이벤트 목록입니다. 아래 허용값 중 필요한 이벤트를 선택하세요. 최대: 4개

첫 번째 요청 · JSON

{}

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "url": "example",
    "work_ids": [
      "11111111-1111-4111-8111-111111111111"
    ],
    "events": [
      "run.state_changed"
    ],
    "enabled": false,
    "verified": false,
    "secret_version": 1,
    "created_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

endpoint_id path *If-Match header * 요청 본문 application/json

서버 응답

Webhook 전송

GET/api/v1/webhook-deliveriesWebhook 보낸 기록 보기

Webhook 전송 시도와 상태를 조회합니다. 알림이 정상 전달됐는지 확인할 때 사용합니다.

필요 권한: webhooks:read

매개변수

이름	타입	필수	설명
`cursor`query	문자열	선택	다음 페이지를 조회할 때 이전 응답의 next_cursor를 그대로 넣으세요. 첫 페이지는 생략하세요. 최소: 1자 최대: 500자
`limit`query	정수	선택	한 번에 가져올 항목 수입니다. 생략하면 아래 기본값을 사용합니다. 생략 시: 20 최솟값: 1 최댓값: 100

응답

HTTP 200 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "endpoint_id": "11111111-1111-4111-8111-111111111111",
        "event_id": "11111111-1111-4111-8111-111111111111",
        "state": "pending",
        "attempt": 0,
        "http_status": 1,
        "next_attempt_at": "2026-09-20T00:00:00Z",
        "created_at": "2026-09-20T00:00:00Z"
      }
    ],
    "next_cursor": "example"
  }
}

응답 헤더: X-Request-Id · ETag

오류 응답 · error.code ↗

직접 호출

cursor query limit query

서버 응답

POST/api/v1/webhook-deliveries/{delivery_id}/redeliverWebhook 다시 보내기

delivery_id로 지정한 기존 Webhook 알림을 다시 전송하도록 요청합니다.

필요 권한: webhooks:write

매개변수

이름	타입	필수	설명
`delivery_id`path	문자열	필수	다시 전송할 웹훅 전송 기록의 id입니다. 형식: UUID (조회 응답의 id 사용)
`Idempotency-Key`header	문자열	필수	중복 실행을 막기 위한 요청 고유값입니다. 예: upload-20260921-0001. 같은 요청을 재시도할 때는 본문과 이 값을 그대로 사용하세요. 최소: 16자 최대: 128자

요청 본문

첫 번째 요청 · JSON

{}

응답

HTTP 202 성공

첫 번째 요청 · JSON

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "endpoint_id": "11111111-1111-4111-8111-111111111111",
    "event_id": "11111111-1111-4111-8111-111111111111",
    "state": "pending",
    "attempt": 0,
    "http_status": 1,
    "next_attempt_at": "2026-09-20T00:00:00Z",
    "created_at": "2026-09-20T00:00:00Z"
  }
}

응답 헤더: X-Request-Id · ETag · Retry-After

오류 응답 · error.code ↗

직접 호출

delivery_id path *Idempotency-Key header * 요청 본문 application/json

서버 응답

명세서

GET/api/v1/openapi.jsonAPI 명세 내려받기

API 경로·요청 필드·응답 구조가 담긴 OpenAPI 명세를 내려받습니다.

매개변수

매개변수 없음

응답

HTTP 200 OpenAPI 명세

첫 번째 요청 · JSON

{}

직접 호출

서버 응답

오류 응답 · error.code 71

2xx 응답은 요청이 잘 전달됐다는 뜻입니다. 201은 새로 만들어졌다는 뜻이고, 202는 접수는 됐지만 아직 만드는 중이라 결과가 나오지 않았다는 뜻입니다. 202를 받으면 작업 상태를 조회해 끝났는지 확인하세요. 성공 응답에는 request_id와 data가 들어 있습니다. 파일 다운로드와 API 명세 응답만 예외입니다. 실패하면 어떤 엔드포인트든 똑같은 모양의 error를 돌려줍니다. 코드에서 분기할 때는 error.code를 쓰고, message는 원인과 해결 방법을 사람이 읽으라고 넣은 문장입니다. 다시 보내도 되는지는 retryable로 판단하세요. true일 때만 자동으로 재시도하고, retry_after_seconds나 Retry-After에 적힌 시간만큼 기다린 뒤 보냅니다. POST를 다시 보낼 때는 처음과 같은 Idempotency-Key와 같은 본문을 써야 중복 결제나 중복 생성이 생기지 않습니다. 처음 보는 error.code가 오면 HTTP 상태와 retryable만 보고 처리하면 됩니다. 문의할 때는 request_id를 함께 알려 주세요. 작업이 접수된 뒤에 생긴 실패는 이 응답이 아니라 작업 상태와 결과에서 확인할 수 있습니다.

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid input. Check the required fields, types and values.",
    "retryable": false
  }
}

error.code	HTTP	설명
`INVALID_REFERENCE`	422	선택한 참조 이미지를 사용할 수 없습니다. 이 작품의 준비된 이미지를 다시 선택하세요.
`MODEL_UNAVAILABLE`	422	선택한 모델을 사용할 수 없습니다. 모델 목록을 새로고침한 뒤 다시 선택해 주세요.
`MODEL_POLICY_REQUIRED`	503	기본 모델 정책이 설정되지 않았습니다. 모델을 지정하거나 관리자에게 설정을 요청해 주세요.
`BUILD_REPLAY_CONFLICT`	409	빌드 입력이 변경되었습니다. 저장된 작업을 확인하세요.
`INVALID_REQUEST`	400,422	입력값이 잘못되었습니다. 필수 필드, 타입과 값을 확인하세요.
`INVALID_API_KEY`	401	API 키 또는 다운로드 서명이 유효하지 않습니다. 키를 확인하거나 다운로드 URL을 새로 발급받으세요.
`INSUFFICIENT_SCOPE`	403	권한이 부족합니다. 키의 scope와 작품 접근 권한을 확인하세요.
`PARTNER_BLOCKED`	403	계정이 차단되었습니다. 지원팀에 문의하세요.
`PARTNER_PAUSED`	403	계정이 일시 중지되었습니다. 관리자에게 재개를 요청하세요.
`RESOURCE_NOT_FOUND`	404	리소스를 찾을 수 없습니다. ID와 접근 권한을 확인하세요.
`METHOD_NOT_ALLOWED`	405	지원하지 않는 HTTP 메서드입니다. 명세의 메서드를 사용하세요.
`REQUEST_TIMEOUT`	408	요청 본문 수신 시간이 초과되었습니다. 연결과 업로드 크기를 확인하세요.
`IDEMPOTENCY_KEY_REQUIRED`	400	유효한 Idempotency-Key 헤더를 지정하세요.
`IDEMPOTENCY_CONFLICT`	409	같은 Idempotency-Key에 다른 요청이 전달되었습니다. 원래 요청에만 같은 키를 사용하세요.
`IDEMPOTENCY_KEY_EXPIRED`	409	멱등성 기록이 만료되었습니다. 새 작업을 시작하기 전에 기존 결과를 확인하세요.
`PRECONDITION_FAILED`	412	최신 ETag를 따옴표와 함께 If-Match에 지정하세요.
`REVISION_CONFLICT`	409	리소스가 변경되었습니다. 최신 버전을 조회한 뒤 수정하세요.
`RESOURCE_CONFLICT`	409	기존 데이터와 충돌합니다. 현재 리소스를 확인하세요.
`INVALID_TRANSITION`	409	현재 상태에서 실행할 수 없는 작업입니다. 최신 상태를 확인하세요.
`RUN_IN_PROGRESS`	409	실행 중인 작업이 있습니다. 진행 상태를 확인하세요.
`JOB_RUNNING`	409	작업이 실행 중입니다. 완료 후 수정하세요.
`PLAN_EXPIRED`	409	계획이 만료되었습니다. 새 계획과 견적을 확인하세요.
`INSUFFICIENT_CREDITS`	402	크레딧이 부족합니다. 잔액과 필요한 크레딧을 확인하세요.
`BUDGET_EXCEEDED`	409,429	예산 한도를 초과했습니다. 사용량과 설정된 예산을 확인하세요.
`RATE_LIMITED`	429	요청 빈도를 초과했습니다. retryable과 Retry-After를 확인하세요.
`CAPACITY_EXCEEDED`	429	처리 한도를 초과했습니다. 작업량을 줄이거나 실행 중인 작업의 완료를 기다리세요.
`PAYLOAD_TOO_LARGE`	413	요청 본문이 너무 큽니다. 명세의 크기 제한에 맞게 줄이세요.
`UNSUPPORTED_MEDIA_TYPE`	415	지원하지 않는 형식 또는 인코딩입니다. 명세의 Content-Type을 사용하고 Content-Encoding을 제거하세요.
`UPLOAD_TOO_LARGE`	422	업로드 콘텐츠가 처리 제한을 초과합니다. 파일 크기를 줄이세요.
`UPLOAD_NOT_VERIFIED`	422	업로드가 미완료, 만료 또는 검증 실패 상태입니다. 업로드와 검증 단계를 확인하세요.
`ASSET_KIND_MISMATCH`	422	에셋 종류가 작업과 맞지 않습니다. 호환되는 에셋을 선택하세요.
`SELECTED_IMAGE_REQUIRED`	422	영상 생성 전에 유효한 이미지를 선택하세요.
`SELECTED_VIDEO_REQUIRED`	422	합성할 샷에 유효한 영상을 선택하세요.
`REFERENCE_LIMIT_EXCEEDED`	422	참조 에셋이 너무 많습니다. 모델 제한에 맞게 줄이세요.
`REFERENCE_IMAGE_REQUIRED`	422	이 모델에는 참조 이미지가 필요합니다. 이미지를 추가하거나 텍스트로 이미지를 생성하는 모델을 선택하세요.
`INVALID_GENERATION_OPTIONS`	422	생성 옵션이 유효하지 않습니다. 모델이 지원하는 옵션을 확인하세요.
`PROMPT_REQUIRED`	422	생성 프롬프트를 입력하세요.
`SCRIPT_TEXT_REQUIRED`	422	작업 시작 전에 대본 내용을 입력하세요.
`SCENES_REQUIRED`	422	작업 시작 전에 씬을 생성하세요.
`VARIANT_NAME_REQUIRED`	422	변형 이름을 입력하세요.
`EPISODE_ALREADY_STRUCTURED`	409	에피소드에 이미 샷이 있습니다. 기존 구성을 확인하세요.
`ONE_SCRIPT_PER_PROJECT`	409	작품는 대본 하나를 지원합니다. 기존 대본을 사용하세요.
`MULTIPLE_SCRIPTS_REQUIRE_REVIEW`	409	여러 대본이 있어 진행 전 검토가 필요합니다.
`NATIVE_CONTENT_ALREADY_EXISTS`	409	Studio 콘텐츠가 이미 있습니다. 기존 내용을 확인하세요.
`LIVE_PROJECT_REQUIRED`	409	이 작업에는 라이브 작품가 필요합니다.
`STUDIO_MIGRATION_REQUIRED`	409	작품의 Studio 전환이 필요합니다. 지원팀에 문의하세요.
`UNSUPPORTED_CAPABILITY`	422	지원하지 않는 기능 또는 프로필입니다. GET /capabilities를 확인하세요.
`CAPABILITY_UNAVAILABLE`	503	현재 기능을 사용할 수 없습니다. GET /capabilities를 확인하세요.
`API_NOT_ACCEPTING`	503	새 요청 접수가 중지되었습니다. 서비스 상태를 확인하세요.
`DEPENDENCY_UNAVAILABLE`	503	필수 서비스를 사용할 수 없습니다. 재시도 안내를 따르거나 지원팀에 문의하세요.
`PRICING_UNAVAILABLE`	503	가격을 확인할 수 없습니다. 진행하려면 유효한 견적이 필요합니다.
`MEDIA_TOOLS_UNAVAILABLE`	503	미디어 처리를 사용할 수 없습니다. 지원팀에 문의하세요.
`STORAGE_READ_FAILED`	503	저장된 에셋을 읽지 못했습니다. request_id와 함께 지원팀에 문의하세요.
`STORAGE_WRITE_FAILED`	503	에셋 저장에 실패했습니다. 재시도 전에 결과를 확인하세요.
`INTERNAL_ERROR`	500	내부 오류입니다. 재시도 안내를 따르고 문의 시 request_id를 전달하세요.
`RESPONSE_CONTRACT_VIOLATION`	500	서버 응답 검증에 실패했습니다. request_id와 함께 지원팀에 문의하세요.
`INVALID_EXECUTION_CONTEXT`	500	실행 정보가 유효하지 않습니다. 지원팀에 문의하세요.
`RETRY_TRANSACTION`	503	트랜잭션을 완료하지 못했습니다. 응답의 재시도 안내를 따르세요.
`CLAIM_LOST`	409	작업 실행 담당이 변경되었습니다. 현재 작업 상태를 확인하세요.
`PROVIDER_TIMEOUT`	504	생성 서비스 응답 시간이 초과되었습니다. 재요청 전에 기존 작업을 확인하세요.
`PROVIDER_TERMINAL_FAILURE`	422	생성이 실패했습니다. 작업 결과와 입력을 확인하세요.
`PROVIDER_RESULT_UNAVAILABLE`	502	생성 결과를 가져올 수 없습니다. 기존 작업과 복구 가능 여부를 확인하세요.
`INVALID_RESULT`	422,503	결과 검증에 실패했습니다. 작업을 확인하거나 지원팀에 문의하세요.
`RESULT_TOO_LARGE`	422	결과가 처리 제한을 초과합니다. 출력 규모를 줄이세요.
`EXPORT_TOO_LARGE`	422	내보내기 크기가 제한을 초과합니다. 선택 범위를 줄이세요.
`RECOVERY_BACKOFF`	409	기존 결과 조회의 재시도 대기 중입니다. 새로 생성하지 말고 잠시 후 다시 확인하세요.
`VIDEO_RECOVERY_REVIEW_REQUIRED`	503	기존 영상 작업의 결과를 복구하거나 운영 점검해야 합니다. 새로 생성하지 마세요.
`RESULT_RECOVERY_REQUIRED`	409,503	기존 결과 복구가 필요합니다. 재요청 전에 실행의 복구 옵션을 확인하세요.
`RESULT_NOT_RECOVERABLE`	409	이 작업으로 결과를 복구할 수 없습니다. 실행을 확인하거나 지원팀에 문의하세요.
`RECOVERY_CAPACITY_EXCEEDED`	409	복구 한도에 도달했습니다. 추가 시도 전에 지원팀에 문의하세요.
`USAGE_RECOVERY_REQUIRED`	503	사용량 확인이 필요합니다. 생성을 반복 요청하지 말고 지원팀에 문의하세요.