Authenticate
Use your FECINE API key as a Bearer token. Reading these docs needs no account.
FECINE OPEN API v1.1.0
API reference
Build your production workflow with FECINE. From screenplay to final cut, one API.
Create and run
Create a work, upload scripts and materials, then add characters, background scenes, props and grids. Create episodes and scenes, attach references and generate scene videos. Select a take for each scene, then export the final cut. Wait for each generation job to finish and send the latest revision when editing. To build a structure from uploaded scripts, explicitly run the build operation.
Collect results
Poll the job or receive a webhook. Use asset IDs to retrieve signed download links.
Your first request
curl -X GET 'https://YOUR_FECINE_HOST/api/v1/capabilities' \
-H 'Authorization: Bearer YOUR_FECINE_API_KEY'REFERENCE
API reference
No matching endpoints
FECINE error. Include request_id when contacting support.
Copy the JSON example and replace IDs, URLs and content with your actual values.
Capabilities
GET/api/v1/capabilitiesSee what you can do right now
Lists available operations, models, upload formats and production limits for the current API environment.
Required scope: projects:read
Parameters
No parameters
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
Projects & resources
GET/api/v1/worksList your projects
Lists accessible projects. Filter by state and use cursor and limit to page through results.
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorquery | string | — |
|
limitquery | integer | — |
|
statequery | string | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/worksCreate a new project
Creates a project with the supplied name. Use the returned project ID to add material and start production.
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
client_reference | string | — |
|
Your first request · JSON
{
"name": "example"
}Responses
HTTP 201 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{project_id}View a project
Returns a project’s name, state and current revision. Read this before submitting changes or production requests.
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{project_id}Edit a project
Changes a project’s name or switches its state between active and archived. Send the latest ETag in If-Match.
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
If-Matchheader | string | * | Use the latest ETag, including quotes. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | — |
|
state | string | — |
|
Your first request · JSON
{}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{project_id}/resourcesList the material you uploaded
Lists a project’s script, character, scene, prop, episode and shot records. Use kind to select a resource type.
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
kindquery | string | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/resourcesAdd material such as scripts and images
Adds a structured resource to a project using kind and data, such as script text or a shot definition. Upload file bytes through /uploads.
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
kind | string | * | kind = script
|
name | string | * | kind = script
|
data | object | * | kind = scriptProvide exactly one of text or source_asset_id. |
data.text | string | — | kind = script
|
data.source_asset_id | string | — | kind = script
|
data.language | string | * | kind = script
|
kind | string | * | kind = character
|
name | string | * | kind = character
|
data | object | * | kind = character |
data.description | string | * | kind = character
|
data.reference_asset_ids | array | — | kind = character
|
kind | string | * | kind = scene
|
name | string | * | kind = scene
|
data | object | * | kind = scene |
data.description | string | * | kind = scene
|
data.reference_asset_ids | array | — | kind = scene
|
kind | string | * | kind = prop
|
name | string | * | kind = prop
|
data | object | * | kind = prop |
data.description | string | * | kind = prop
|
data.reference_asset_ids | array | — | kind = prop
|
kind | string | * | kind = episode
|
name | string | * | kind = episode
|
data | object | * | kind = episode |
data.script_resource_id | string | * | kind = episode
|
data.sequence | integer | * | kind = episode
|
data.raw_content | string | — | kind = episode
|
data.description | string | — | kind = episode
|
kind | string | * | kind = shot
|
name | string | * | kind = shot
|
data | object | * | kind = shot |
data.episode_id | string | * | kind = shot
|
data.scene_id | string | — | kind = shot
|
data.character_ids | array | — | kind = shot
|
data.prop_ids | array | — | kind = shot
|
data.description | string | * | kind = shot
|
data.video_prompt | oneOf | — | kind = shot |
data.sequence | integer | — | kind = shot
|
data.duration_seconds | integer | * | kind = shot
|
data.selected_image_asset_id | string | — | kind = shot
|
data.selected_video_asset_id | string | — | kind = shot
|
Your first request · JSON
{
"kind": "script",
"name": "example",
"data": {
"language": "example"
}
}Responses
HTTP 201 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{project_id}/resources/{resource_id}View one piece of material
Returns the kind, data and revision of one resource identified by resource_id within the project.
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
resource_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{project_id}/resources/{resource_id}Edit material
Updates a resource’s kind and data. Send its latest ETag in If-Match to protect against conflicting edits.
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
resource_idpath | string | * |
|
If-Matchheader | string | * | Use the latest ETag, including quotes. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
kind | string | * | kind = script
|
name | string | * | kind = script
|
data | object | * | kind = scriptProvide exactly one of text or source_asset_id. |
data.text | string | — | kind = script
|
data.source_asset_id | string | — | kind = script
|
data.language | string | * | kind = script
|
kind | string | * | kind = character
|
name | string | * | kind = character
|
data | object | * | kind = character |
data.description | string | * | kind = character
|
data.reference_asset_ids | array | — | kind = character
|
kind | string | * | kind = scene
|
name | string | * | kind = scene
|
data | object | * | kind = scene |
data.description | string | * | kind = scene
|
data.reference_asset_ids | array | — | kind = scene
|
kind | string | * | kind = prop
|
name | string | * | kind = prop
|
data | object | * | kind = prop |
data.description | string | * | kind = prop
|
data.reference_asset_ids | array | — | kind = prop
|
kind | string | * | kind = episode
|
name | string | * | kind = episode
|
data | object | * | kind = episode |
data.script_resource_id | string | * | kind = episode
|
data.sequence | integer | * | kind = episode
|
data.raw_content | string | — | kind = episode
|
data.description | string | — | kind = episode
|
kind | string | * | kind = shot
|
name | string | * | kind = shot
|
data | object | * | kind = shot |
data.episode_id | string | * | kind = shot
|
data.scene_id | string | — | kind = shot
|
data.character_ids | array | — | kind = shot
|
data.prop_ids | array | — | kind = shot
|
data.description | string | * | kind = shot
|
data.video_prompt | oneOf | — | kind = shot |
data.sequence | integer | — | kind = shot
|
data.duration_seconds | integer | * | kind = shot
|
data.selected_image_asset_id | string | — | kind = shot
|
data.selected_video_asset_id | string | — | kind = shot
|
Your first request · JSON
{
"kind": "script",
"name": "example",
"data": {
"language": "example"
}
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{project_id}/workflowRead Studio production data
Returns the project’s script, episodes, designs, scenes, assets, takes and cut selections together with the latest revision.
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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
}
]
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/script/analysesAnalyze the Studio script
Analyzes the project script into production structure. Provide script_text to update the script before analysis, or omit it to use the saved script. Track the returned job with getJob.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
model | string | — |
|
script_text | string | — |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
POST/api/v1/works/{project_id}/script/buildsBuild production from script
Send verified script_asset_ids and revision to build the screenplay, references and storyboard. full_rebuild replaces existing structure. Generate images and videos separately. Charges reported input and output tokens at the same prices as Studio. No per-request credit budget is required. GET /jobs/{job_id} → output_asset_ids.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
model | string | — |
|
script_asset_ids | array | — |
|
material_scope | string | — |
|
preprocess | object | — | |
preprocess.ignoreAttachments | boolean | — |
|
preprocess.discardKeywords | array | — |
|
preprocess.keepLabels | array | — |
|
rebuild_policy | string | * |
|
Your first request · JSON
{
"revision": 1,
"rebuild_policy": "full_rebuild"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
GET/api/v1/works/{project_id}/libraryList shared library assets
Lists assets available to import into the project. scope=personal lists your own library; scope=studio, the default, lists the shared library.
Required scope: assets:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
limit | integer | — |
|
cursor | string | — | |
scope | string | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/importsImport an asset into a project
Copies the asset identified by asset_id from a personal or shared library into the project. Returns the project-owned copy; later source changes do not affect it.
Required scope: assets:write, assets:read, projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
asset_id | string | * |
|
Your first request · JSON
{
"revision": 1,
"asset_id": "11111111-1111-4111-8111-111111111111"
}Responses
HTTP 201 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/script/draftsGenerate screenplay draft
Send instructions, optional source_text, revision and max_output_tokens. Saves a new script asset without replacing the existing screenplay. Charges reported input and output tokens at the same prices as Studio. No per-request credit budget is required. GET /jobs/{job_id} → output_asset_ids.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
model | string | — |
|
instructions | string | * |
|
source_text | string | — |
|
max_output_tokens | integer | — |
|
Your first request · JSON
{
"revision": 1,
"instructions": "example"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
GET/api/v1/works/{work_id}/charactersCharacter · Read (list)
Character · Read (list). GET /api/v1/works/{work_id}/characters. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/charactersCharacter · Create
Character · Create. POST /api/v1/works/{work_id}/characters. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/characters/{reference_id}Character · Read
Character · Read. GET /api/v1/works/{work_id}/characters/{reference_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/characters/{reference_id}Character · Update
Character · Update. PATCH /api/v1/works/{work_id}/characters/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/characters/{reference_id}Character · Delete
Character · Delete. DELETE /api/v1/works/{work_id}/characters/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/characters/{reference_id}/primary-imageCharacter · Set reference image
Character · Set reference image. PUT /api/v1/works/{work_id}/characters/{reference_id}/primary-image. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
asset_id | string | * |
|
current_asset_id | oneOf | * | |
revision | integer | * |
Your first request · JSON
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"current_asset_id": "11111111-1111-4111-8111-111111111111",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/characters/{reference_id}/image-generationsCharacter · Generate reference image
Character · Generate reference image. POST /api/v1/works/{work_id}/characters/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
variants | integer | — |
|
model | string | — |
|
prompt | string | — |
|
aspect_ratio | string | — | |
image_size | string | — |
|
quality | string | — |
|
background | string | — |
|
output_format | string | — |
|
reference_asset_ids | array | — |
|
slot | string | — |
|
variant_name | string | — |
|
current_asset_id | string | — |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}Character · Attach to scene
Character · Attach to scene. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}Character · Detach from scene
Character · Detach from scene. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/characters/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/background-scenesBackground scene · Read (list)
Background scene · Read (list). GET /api/v1/works/{work_id}/background-scenes. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/background-scenesBackground scene · Create
Background scene · Create. POST /api/v1/works/{work_id}/background-scenes. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/background-scenes/{reference_id}Background scene · Read
Background scene · Read. GET /api/v1/works/{work_id}/background-scenes/{reference_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/background-scenes/{reference_id}Background scene · Update
Background scene · Update. PATCH /api/v1/works/{work_id}/background-scenes/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/background-scenes/{reference_id}Background scene · Delete
Background scene · Delete. DELETE /api/v1/works/{work_id}/background-scenes/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/background-scenes/{reference_id}/primary-imageBackground scene · Set reference image
Background scene · Set reference image. PUT /api/v1/works/{work_id}/background-scenes/{reference_id}/primary-image. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
asset_id | string | * |
|
current_asset_id | oneOf | * | |
revision | integer | * |
Your first request · JSON
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"current_asset_id": "11111111-1111-4111-8111-111111111111",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/background-scenes/{reference_id}/image-generationsBackground scene · Generate reference image
Background scene · Generate reference image. POST /api/v1/works/{work_id}/background-scenes/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
variants | integer | — |
|
model | string | — |
|
prompt | string | — |
|
aspect_ratio | string | — | |
image_size | string | — |
|
quality | string | — |
|
background | string | — |
|
output_format | string | — |
|
reference_asset_ids | array | — |
|
slot | string | — |
|
variant_name | string | — |
|
current_asset_id | string | — |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}Background scene · Attach to scene
Background scene · Attach to scene. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}Background scene · Detach from scene
Background scene · Detach from scene. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/background-scenes/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/propsProp · Read (list)
Prop · Read (list). GET /api/v1/works/{work_id}/props. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/propsProp · Create
Prop · Create. POST /api/v1/works/{work_id}/props. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/props/{reference_id}Prop · Read
Prop · Read. GET /api/v1/works/{work_id}/props/{reference_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/props/{reference_id}Prop · Update
Prop · Update. PATCH /api/v1/works/{work_id}/props/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/props/{reference_id}Prop · Delete
Prop · Delete. DELETE /api/v1/works/{work_id}/props/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/props/{reference_id}/primary-imageProp · Set reference image
Prop · Set reference image. PUT /api/v1/works/{work_id}/props/{reference_id}/primary-image. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
asset_id | string | * |
|
current_asset_id | oneOf | * | |
revision | integer | * |
Your first request · JSON
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"current_asset_id": "11111111-1111-4111-8111-111111111111",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/props/{reference_id}/image-generationsProp · Generate reference image
Prop · Generate reference image. POST /api/v1/works/{work_id}/props/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
variants | integer | — |
|
model | string | — |
|
prompt | string | — |
|
aspect_ratio | string | — | |
image_size | string | — |
|
quality | string | — |
|
background | string | — |
|
output_format | string | — |
|
reference_asset_ids | array | — |
|
slot | string | — |
|
variant_name | string | — |
|
current_asset_id | string | — |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}Prop · Attach to scene
Prop · Attach to scene. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}Prop · Detach from scene
Prop · Detach from scene. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/props/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/gridsGrid · Read (list)
Grid · Read (list). GET /api/v1/works/{work_id}/grids. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/gridsGrid · Create
Grid · Create. POST /api/v1/works/{work_id}/grids. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/grids/{reference_id}Grid · Read
Grid · Read. GET /api/v1/works/{work_id}/grids/{reference_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/grids/{reference_id}Grid · Update
Grid · Update. PATCH /api/v1/works/{work_id}/grids/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | * |
|
description | string | — |
|
tags | array | — |
|
revision | integer | * |
Your first request · JSON
{
"name": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/grids/{reference_id}Grid · Delete
Grid · Delete. DELETE /api/v1/works/{work_id}/grids/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/grids/{reference_id}/primary-imageGrid · Set reference image
Grid · Set reference image. PUT /api/v1/works/{work_id}/grids/{reference_id}/primary-image. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
asset_id | string | * |
|
current_asset_id | oneOf | * | |
revision | integer | * |
Your first request · JSON
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"current_asset_id": "11111111-1111-4111-8111-111111111111",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/grids/{reference_id}/image-generationsGrid · Generate reference image
Grid · Generate reference image. POST /api/v1/works/{work_id}/grids/{reference_id}/image-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
variants | integer | — |
|
model | string | — |
|
prompt | string | — |
|
aspect_ratio | string | — | |
image_size | string | — |
|
quality | string | — |
|
background | string | — |
|
output_format | string | — |
|
reference_asset_ids | array | — |
|
slot | string | — |
|
variant_name | string | — |
|
current_asset_id | string | — |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
PUT/api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}Grid · Attach to scene
Grid · Attach to scene. PUT /api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}Grid · Detach from scene
Grid · Detach from scene. DELETE /api/v1/works/{work_id}/scenes/{scene_id}/references/grids/{reference_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
reference_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/episodesEpisode · Read (list)
Episode · Read (list). GET /api/v1/works/{work_id}/episodes. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/episodesCreate episode
Create episode. POST /api/v1/works/{work_id}/episodes. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
title | string | * |
|
number | integer | — | |
raw_content | string | — |
|
description | string | — |
|
revision | integer | * |
Your first request · JSON
{
"title": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/episodes/{episode_id}Episode · Read
Episode · Read. GET /api/v1/works/{work_id}/episodes/{episode_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · JSON
{
"request_id": "11111111-1111-4111-8111-111111111111",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"number": 1,
"title": "example",
"raw_content": "example",
"description": "example"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/episodes/{episode_id}Episode · Update
Episode · Update. PATCH /api/v1/works/{work_id}/episodes/{episode_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
title | string | * |
|
number | integer | — | |
raw_content | string | — |
|
description | string | — |
|
revision | integer | * |
Your first request · JSON
{
"title": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/episodes/{episode_id}Episode · Delete
Episode · Delete. DELETE /api/v1/works/{work_id}/episodes/{episode_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/episodes/{episode_id}/scenesScene · Read (list)
Scene · Read (list). GET /api/v1/works/{work_id}/episodes/{episode_id}/scenes. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/episodes/{episode_id}/scenesCreate scene
Create scene. POST /api/v1/works/{work_id}/episodes/{episode_id}/scenes. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
heading | string | * |
|
number | integer | — | |
description | string | — |
|
video_prompt | oneOf | — | |
revision | integer | * |
Your first request · JSON
{
"heading": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}Scene · Read
Scene · Read. GET /api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}. GET
Required scope: projects:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
scene_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}Scene · Update
Scene · Update. PATCH /api/v1/works/{work_id}/episodes/{episode_id}/scenes/{scene_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
scene_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
heading | string | * |
|
number | integer | — | |
description | string | — |
|
video_prompt | oneOf | — | |
revision | integer | * |
Your first request · JSON
{
"heading": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/archive-importsImport ZIP archive
Import ZIP archive. POST /api/v1/works/{work_id}/archive-imports. Use a verified ZIP asset_id and current revision. Preserves the archive and uses the same name-based material update rules as Studio. Check imported, failed and asset_ids on completion. Creation requires jobs:create, assets:read, assets:write and projects:write. Idempotency-Key; GET /api/v1/works/{work_id}/archive-imports/{import_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
asset_id | string | * |
|
Your first request · JSON
{
"revision": 1,
"asset_id": "11111111-1111-4111-8111-111111111111"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
GET/api/v1/works/{work_id}/archive-imports/{import_id}Get archive import
Get archive import. GET /api/v1/works/{work_id}/archive-imports/{import_id}. Use a verified ZIP asset_id and current revision. Preserves the archive and uses the same name-based material update rules as Studio. Check imported, failed and asset_ids on completion. Creation requires jobs:create, assets:read, assets:write and projects:write. jobs:read
Required scope: jobs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
import_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/uploadsPrepare file batch upload
Prepare file batch upload. POST /api/v1/works/{work_id}/uploads. Idempotency-Key + files (1–20) → PUT upload_url → POST /api/v1/uploads/{upload_id}/complete
Required scope: assets:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
files | array | * |
|
files[].filename | string | * |
|
files[].mime_type | string | * |
|
files[].size_bytes | integer | * |
|
files[].sha256 | string | * |
Your first request · JSON
{
"files": [
{
"filename": "example",
"mime_type": "text/plain",
"size_bytes": 1,
"sha256": "example"
}
]
}Responses
HTTP 201 Success
Your first request · 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"
}
}
]
}
}Response headers: X-Request-Id · ETag
Try it out
DELETE/api/v1/works/{work_id}/scenes/{scene_id}Scene · Delete
Scene · Delete. DELETE /api/v1/works/{work_id}/scenes/{scene_id}. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * |
Your first request · JSON
{
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/episodes/{episode_id}/scene-orderReorder scenes
Reorder scenes. PUT /api/v1/works/{work_id}/episodes/{episode_id}/scene-order. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
episode_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
scene_ids | array | * |
|
revision | integer | * |
Your first request · JSON
{
"scene_ids": [
"11111111-1111-4111-8111-111111111111"
],
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/works/{work_id}/scriptSave script
Save script. PUT /api/v1/works/{work_id}/script. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
text | string | * |
|
revision | integer | * |
Your first request · JSON
{
"text": "example",
"revision": 1
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/scenes/{scene_id}/video-generationsGenerate scene video
Generate scene video. POST /api/v1/works/{work_id}/scenes/{scene_id}/video-generations. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
anchor_asset_id | string | — |
|
reference_asset_ids | array | — |
|
model | string | — |
|
prompt | string | — |
|
duration_seconds | integer | * |
|
resolution | string | * |
|
aspect_ratio | string | * |
|
generate_audio | boolean | — |
Your first request · JSON
{
"revision": 1,
"duration_seconds": 1,
"resolution": "example",
"aspect_ratio": "example"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
PUT/api/v1/works/{work_id}/scenes/{scene_id}/selected-takeSelect final take
Select final take. PUT /api/v1/works/{work_id}/scenes/{scene_id}/selected-take. revision + Idempotency-Key
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
scene_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
take_id | oneOf | * |
Your first request · JSON
{
"revision": 1,
"take_id": "11111111-1111-4111-8111-111111111111"
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{work_id}/exportsExport final video
Export final video. POST /api/v1/works/{work_id}/exports. revision + Idempotency-Key → GET /api/v1/jobs/{job_id}
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
work_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
allow_partial | boolean | — |
|
selections | array | — |
|
selections[].scene_id | string | * |
|
selections[].asset_id | string | * |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
Legacy integration API
POST/api/v1/works/{project_id}/plansCheck the plan and the credits it will cost
Check what will be produced and how many credits it will cost, without starting the actual production.
Required scope: runs:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
template_id | string | * |
|
template_version | number | * |
|
project_revision | integer | * | |
episode_ids | array | * | Episode IDs must be unique.
|
mode | string | * |
|
output_profile | string | * |
|
Your first request · 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"
}Responses
HTTP 201 Success
Your first request · 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"
]
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/runsStart production
Starts production from an existing plan_id and returns a run ID. Use getRun to track its state and results.
Required scope: runs:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
plan_id | string | * |
|
client_reference | string | — |
|
Your first request · JSON
{
"plan_id": "11111111-1111-4111-8111-111111111111"
}Responses
HTTP 202 Success
Your first request · 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"
]
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
POST/api/v1/works/{project_id}/workflow/commandsEdit Studio production
Edits production data, such as scripts, scenes, designs or selected takes. Choose an operation and send its input with the latest revision.
Required scope: projects:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | operation = design.asset.set |
operation | string | * | operation = design.asset.set
|
input | object | * | operation = design.asset.set |
input.id | string | * | operation = design.asset.set
|
input.asset_id | string | * | operation = design.asset.set
|
input.kind | string | * | operation = design.asset.set
|
input.current_asset_id | oneOf | * | operation = design.asset.set |
input.name | string | — | operation = design.asset.set
|
revision | integer | * | operation = asset.delete |
operation | string | * | operation = asset.delete
|
input | object | * | operation = asset.delete |
input.id | string | * | operation = asset.delete
|
revision | integer | * | operation = trash.restore |
operation | string | * | operation = trash.restore
|
input | object | * | operation = trash.restore |
input.id | string | * | operation = trash.restore
|
input.entity_type | string | * | operation = trash.restore
|
revision | integer | * | operation = scene.duplicate |
operation | string | * | operation = scene.duplicate
|
input | object | * | operation = scene.duplicate |
input.id | string | * | operation = scene.duplicate
|
revision | integer | * | operation = project.settings.update |
operation | string | * | operation = project.settings.update
|
input | object | * | operation = project.settings.update |
input.title | string | * | operation = project.settings.update
|
input.tags | array | * | operation = project.settings.update
|
input.cover | string | * | operation = project.settings.update
|
input.aspect | string | * | operation = project.settings.update
|
input.resolution | string | * | operation = project.settings.update
|
input.style | string | * | operation = project.settings.update
|
input.style_prompt | string | * | operation = project.settings.update
|
revision | integer | * | operation = project.rename |
operation | string | * | operation = project.rename
|
input | object | * | operation = project.rename |
input.title | string | * | operation = project.rename
|
revision | integer | * | operation = project.state.set |
operation | string | * | operation = project.state.set
|
input | object | * | operation = project.state.set |
input.state | string | * | operation = project.state.set
|
revision | integer | * | operation = script.update |
operation | string | * | operation = script.update
|
input | object | * | operation = script.update |
input.text | string | * | operation = script.update
|
revision | integer | * | operation = script.bible.update |
operation | string | * | operation = script.bible.update
|
input | object | * | operation = script.bible.update |
input.logline | string | * | operation = script.bible.update
|
input.synopsis | string | * | operation = script.bible.update
|
revision | integer | * | operation = episode.save |
operation | string | * | operation = episode.save
|
input | object | * | operation = episode.save |
input.id | string | — | operation = episode.save
|
input.title | string | * | operation = episode.save
|
input.number | integer | — | operation = episode.save |
input.raw_content | string | — | operation = episode.save
|
input.description | string | — | operation = episode.save
|
revision | integer | * | operation = episode.delete |
operation | string | * | operation = episode.delete
|
input | object | * | operation = episode.delete |
input.id | string | * | operation = episode.delete
|
revision | integer | * | operation = scene.save |
operation | string | * | operation = scene.save
|
input | object | * | operation = scene.save |
input.id | string | — | operation = scene.save
|
input.episode_id | string | * | operation = scene.save
|
input.heading | string | * | operation = scene.save
|
input.number | integer | — | operation = scene.save |
input.description | string | — | operation = scene.save
|
input.video_prompt | oneOf | — | operation = scene.save |
revision | integer | * | operation = scene.delete |
operation | string | * | operation = scene.delete
|
input | object | * | operation = scene.delete |
input.id | string | * | operation = scene.delete
|
revision | integer | * | operation = scene.reorder |
operation | string | * | operation = scene.reorder
|
input | object | * | operation = scene.reorder |
input.episode_id | string | * | operation = scene.reorder
|
input.scene_ids | array | * | operation = scene.reorder
|
revision | integer | * | operation = design.save |
operation | string | * | operation = design.save
|
input | object | * | operation = design.save |
input.id | string | — | operation = design.save
|
input.kind | string | * | operation = design.save
|
input.name | string | * | operation = design.save
|
input.description | string | — | operation = design.save
|
input.tags | array | — | operation = design.save
|
revision | integer | * | operation = design.delete |
operation | string | * | operation = design.delete
|
input | object | * | operation = design.delete |
input.id | string | * | operation = design.delete
|
revision | integer | * | operation = design.voice.set |
operation | string | * | operation = design.voice.set
|
input | object | * | operation = design.voice.set |
input.id | string | * | operation = design.voice.set
|
input.asset_id | oneOf | * | operation = design.voice.set |
revision | integer | * | operation = design.asset.detach |
operation | string | * | operation = design.asset.detach
|
input | object | * | operation = design.asset.detach |
input.id | string | * | operation = design.asset.detach
|
input.asset_id | string | * | operation = design.asset.detach
|
input.kind | string | * | operation = design.asset.detach
|
revision | integer | * | operation = design.asset.restore |
operation | string | * | operation = design.asset.restore
|
input | object | * | operation = design.asset.restore |
input.id | string | * | operation = design.asset.restore
|
input.current_asset_id | string | * | operation = design.asset.restore
|
input.restore_asset_id | string | * | operation = design.asset.restore
|
input.kind | string | * | operation = design.asset.restore
|
revision | integer | * | operation = design.variant.rename |
operation | string | * | operation = design.variant.rename
|
input | object | * | operation = design.variant.rename |
input.id | string | * | operation = design.variant.rename
|
input.asset_id | string | * | operation = design.variant.rename
|
input.name | string | * | operation = design.variant.rename
|
revision | integer | * | operation = scene.design.attach |
operation | string | * | operation = scene.design.attach
|
input | object | * | operation = scene.design.attach |
input.scene_id | string | * | operation = scene.design.attach
|
input.design_id | string | * | operation = scene.design.attach
|
revision | integer | * | operation = scene.design.detach |
operation | string | * | operation = scene.design.detach
|
input | object | * | operation = scene.design.detach |
input.scene_id | string | * | operation = scene.design.detach
|
input.design_id | string | * | operation = scene.design.detach
|
revision | integer | * | operation = cut.take.select |
operation | string | * | operation = cut.take.select
|
input | object | * | operation = cut.take.select |
input.scene_id | string | * | operation = cut.take.select
|
input.asset_id | oneOf | * | operation = cut.take.select |
revision | integer | * | operation = take.delete |
operation | string | * | operation = take.delete
|
input | object | * | operation = take.delete |
input.scene_id | string | * | operation = take.delete
|
input.asset_id | string | * | operation = take.delete
|
Your first request · 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"
}
}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/works/{project_id}/cut/exportsExport Studio cut
Joins selected scene videos in episode and scene order. Use selections to choose takes explicitly and allow_partial to permit missing scenes. Track the export with getJob.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
allow_partial | boolean | — |
|
selections | array | — |
|
selections[].scene_id | string | * |
|
selections[].asset_id | string | * |
|
Your first request · JSON
{
"revision": 1
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
POST/api/v1/works/{project_id}/storyboard/videosGenerate storyboard scene video
Generates a video take for scene_id using the selected model, duration and resolution. anchor_asset_id can specify the starting image. Track the returned job with getJob.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
scene_id | string | * |
|
anchor_asset_id | string | — |
|
reference_asset_ids | array | — |
|
model | string | — |
|
prompt | string | — |
|
duration_seconds | integer | * |
|
resolution | string | * |
|
aspect_ratio | string | * |
|
generate_audio | boolean | — |
Your first request · JSON
{
"revision": 1,
"scene_id": "11111111-1111-4111-8111-111111111111",
"duration_seconds": 1,
"resolution": "example",
"aspect_ratio": "example"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
POST/api/v1/works/{project_id}/designs/imagesGenerate character, setting, prop or grid images
Generates one to four images for design_id, using a prompt and optional reference images. Choose a primary or variant slot and track the job with getJob.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
revision | integer | * | |
design_id | string | * |
|
variants | integer | — |
|
model | string | — |
|
prompt | string | — |
|
aspect_ratio | string | — | |
image_size | string | — |
|
quality | string | — |
|
background | string | — |
|
output_format | string | — |
|
reference_asset_ids | array | — |
|
slot | string | — |
|
variant_name | string | — |
|
current_asset_id | string | — |
|
Your first request · JSON
{
"revision": 1,
"design_id": "11111111-1111-4111-8111-111111111111"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
Uploads
POST/api/v1/uploadsGet an address to upload a file to
Registers file metadata and returns an upload_url. PUT the file bytes there, then call the upload completion endpoint. Supports TXT, Markdown, DOCX, PNG, JPEG, WebP, AVIF, WAV and ZIP. Byte limits share Studio settings: read upload_limits from GET /capabilities. Scripts allow up to 5,000,000 characters. Filenames cannot contain path separators. WAV must use PCM or IEEE float.
Required scope: assets:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | * |
|
filename | string | * |
|
mime_type | string | * |
|
size_bytes | integer | * |
|
sha256 | string | * |
Your first request · JSON
{
"project_id": "11111111-1111-4111-8111-111111111111",
"filename": "example",
"mime_type": "text/plain",
"size_bytes": 1,
"sha256": "example"
}Responses
HTTP 201 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/uploads/{upload_id}/completeTell us the file is fully uploaded
Validates the uploaded file against its declared metadata and returns the asset that can be used in production.
Required scope: assets:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
upload_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
Your first request · JSON
{}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
PUT/api/v1/uploads/{upload_id}/contentUpload the file contents
Sends the raw file bytes for an existing upload ticket as application/octet-stream. Call completeUpload after the transfer succeeds.
Required scope: assets:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
upload_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · JSON
{
"request_id": "11111111-1111-4111-8111-111111111111",
"data": {
"uploaded": true
}
}Response headers: X-Request-Id · ETag
Try it out
Assets & results
GET/api/v1/assets/{asset_id}View a result file and its download link
Returns asset metadata and a signed download_url when available. Use that URL to download the file before it expires.
Required scope: assets:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
asset_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/downloads/{asset_id}Download the finished file
Downloads the file bytes using the complete signed download_url returned by getAsset. The link expires after five minutes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
asset_idpath | string | * |
|
expiresquery | string | * | |
signaturequery | string | * |
Responses
HTTP 200 File bytes
application/octet-stream · File bytes
Try it out
Production runs
GET/api/v1/runsList your production runs
Lists production runs, with filters for project, state, client_reference and date range.
Required scope: runs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorquery | string | — |
|
limitquery | integer | — |
|
project_idquery | string | — |
|
statequery | string | — |
|
client_referencequery | string | — |
|
fromquery | string | — |
|
toquery | string | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/runs/{run_id}Check how a run is going
Returns the current state, version and available results of a production run. Use its version when submitting a decision.
Required scope: runs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
]
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/runs/{run_id}/stepsSee progress step by step
Lists the individual steps of a run so you can see which stages are waiting, running or finished.
Required scope: runs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/runs/{run_id}/eventsSee what happened during a run
Lists recorded events for a run, such as state changes and review requests, to trace what happened during production.
Required scope: runs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_idpath | string | * |
|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/runs/{run_id}/decisionsApprove or stop a run
Submits a decision for a run: approve, stop, resume, cancel_remaining or retry_result. Send its latest version as expected_version. retry_result resumes result polling for a saved video task. Send the latest expected_version and step_id. It retains the original job and credit hold without generating again. Only recoverable videos within 24 hours of run admission are supported. Other unknown results or usage require operator review.
Required scope: runs:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
run_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
action | string | * | retry_result resumes result polling for an accepted Studio video on the original reservation; requires step_id and expected_version. It never resubmits generation. Unconfirmed usage without a saved video task requires operator review.
|
expected_version | integer | * | |
step_id | string | — |
|
selected_asset_ids | array | — |
|
Your first request · JSON
{
"action": "approve",
"expected_version": 1
}Responses
HTTP 202 Success
Your first request · 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"
]
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
Workflow functions
GET/api/v1/jobs/{job_id}Check a job and its result
Returns a job’s current state and output asset IDs. Once complete, use getAsset to retrieve its result files.
Required scope: jobs:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
job_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/jobs/{job_id}/buildRead build progress and sources
Returns a script build job’s stage, progress messages and source documents, including the text prepared for processing.
Required scope: jobs:read, assets:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
job_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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
}
]
}
}Response headers: X-Request-Id · ETag
Try it out
Legacy integration API
POST/api/v1/jobsRun a single feature right away
Run just one feature instead of the whole production. analyze_script reads the script and creates shots, generate_image makes character, scene, prop and shot images, generate_video makes the video for a shot whose image you picked, and assemble_video joins an episode whose shots all have a video. Always send the project’s latest revision. Live requests reserve credits up front.
Required scope: jobs:create
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | * |
|
project_revision | integer | * | |
target_id | string | * |
|
type | string | * |
|
profile_id | string | * |
|
client_reference | string | — |
|
Your first request · JSON
{
"project_id": "11111111-1111-4111-8111-111111111111",
"project_revision": 1,
"target_id": "11111111-1111-4111-8111-111111111111",
"type": "analyze_script",
"profile_id": "example"
}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
Request logs
GET/api/v1/requestsList the requests you sent
Lists API request logs with HTTP status and duration. Filter by project and date range to investigate calls.
Required scope: requests:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorquery | string | — |
|
limitquery | integer | — |
|
fromquery | string | — |
|
toquery | string | — |
|
project_idquery | string | — |
|
run_idquery | string | — |
|
job_idquery | string | — |
|
key_idquery | string | — |
|
status_codequery | integer | — |
|
methodquery | string | — |
|
route_templatequery | string | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
GET/api/v1/requests/{request_id}View one request you sent
Looks up one API call by request_id, including its HTTP status, duration and associated run or job.
Required scope: requests:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
request_idpath | string | * |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
Usage
GET/api/v1/usageCheck your credit usage
Returns usage totals for the requested period, including reserved and settled amounts.
Required scope: usage:read
Parameters
No parameters
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
Webhooks
GET/api/v1/webhook-endpointsList your webhook addresses
Lists registered webhook URLs and their event subscriptions and enabled state.
Required scope: webhooks:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/webhook-endpointsAdd a webhook address
Registers a webhook URL to receive the selected production events for the specified projects.
Required scope: webhooks:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
| Name | Type | Required | Description |
|---|---|---|---|
url | string | * |
|
project_ids | array | * |
|
events | array | * |
|
Your first request · JSON
{
"url": "example",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"events": [
"run.state_changed"
]
}Responses
HTTP 201 Success
Your first request · 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"
}
}
}Response headers: X-Request-Id · ETag
Try it out
PATCH/api/v1/webhook-endpoints/{endpoint_id}Edit a webhook address
Enables or disables a webhook endpoint, or changes the events it receives.
Required scope: webhooks:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
endpoint_idpath | string | * |
|
If-Matchheader | string | * | Use the latest ETag, including quotes. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | — | |
events | array | — |
|
Your first request · JSON
{}Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
Webhook deliveries
GET/api/v1/webhook-deliveriesSee what was sent to your webhook
Lists webhook delivery attempts and their status so you can check whether notifications were delivered.
Required scope: webhooks:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorquery | string | — |
|
limitquery | integer | — |
|
Responses
HTTP 200 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag
Try it out
POST/api/v1/webhook-deliveries/{delivery_id}/redeliverSend a webhook again
Requests another delivery of an existing webhook notification identified by delivery_id.
Required scope: webhooks:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
delivery_idpath | string | * |
|
Idempotency-Keyheader | string | * | Retry with the same Idempotency-Key and request body.
|
Request body
Your first request · JSON
{}Responses
HTTP 202 Success
Your first request · 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"
}
}Response headers: X-Request-Id · ETag · Retry-After
Try it out
Specification
GET/api/v1/openapi.jsonDownload the API specification
Downloads the OpenAPI specification containing API paths, request fields and response schemas.
Parameters
No parameters
Responses
HTTP 200 OpenAPI document
Your first request · JSON
{}Try it out
Error responses · error.code 71
A 2xx response means the request went through. 201 means something was created; 202 means we accepted it and are still working, so there is no result yet — poll the job state to see when it finishes. Successful responses contain request_id and data. File downloads and the API specification are the only exceptions. When something fails, every endpoint returns the same error shape. Branch your code on error.code; message is there to tell a person the cause and what to do. Use retryable to decide whether to send the request again. Retry automatically only when it is true, and wait as long as retry_after_seconds or the Retry-After header says. When you retry a POST, send the same Idempotency-Key and the same body so nothing is charged or created twice. If you get an error.code you do not recognise, handle it from the HTTP status and retryable. Include request_id when you contact support. Failures that happen after a job is accepted show up in the job state and its result, not in this response.
{
"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 | Description |
|---|---|---|
INVALID_REFERENCE | 422 | A selected reference is unavailable or does not belong to this project. Select a ready image from this project. |
MODEL_UNAVAILABLE | 422 | The selected model is unavailable. Refresh the model list and select another model. |
MODEL_POLICY_REQUIRED | 503 | No default model policy is configured. Specify a model or ask the administrator to configure the task policy. |
BUILD_REPLAY_CONFLICT | 409 | The build inputs changed. Review the saved build before continuing. |
INVALID_REQUEST | 400,422 | Invalid input. Check the required fields, types and values. |
INVALID_API_KEY | 401 | Invalid credentials or download signature. Check the API key or obtain a new download URL. |
INSUFFICIENT_SCOPE | 403 | Permission denied. Check the key scopes and project access. |
PARTNER_BLOCKED | 403 | Account blocked. Contact support. |
PARTNER_PAUSED | 403 | Account paused. Ask the administrator to resume access. |
RESOURCE_NOT_FOUND | 404 | Resource unavailable. Check its ID and access permissions. |
METHOD_NOT_ALLOWED | 405 | Unsupported HTTP method. Use the documented method. |
REQUEST_TIMEOUT | 408 | Request body timed out. Check the connection and upload size. |
IDEMPOTENCY_KEY_REQUIRED | 400 | Provide a valid Idempotency-Key header. |
IDEMPOTENCY_CONFLICT | 409 | This Idempotency-Key belongs to a different request. Reuse it only with the original request. |
IDEMPOTENCY_KEY_EXPIRED | 409 | Idempotency record expired. Check the original result before starting a new operation. |
PRECONDITION_FAILED | 412 | Provide the latest quoted ETag in If-Match. |
REVISION_CONFLICT | 409 | Resource changed. Read the latest revision before updating. |
RESOURCE_CONFLICT | 409 | Resource conflicts with existing data. Review the current resource. |
INVALID_TRANSITION | 409 | Action is unavailable in the current state. Read the latest state. |
RUN_IN_PROGRESS | 409 | A run is in progress. Check its status before starting another. |
JOB_RUNNING | 409 | A job is running. Wait for completion before editing. |
PLAN_EXPIRED | 409 | Plan expired. Create a new plan and review its quote. |
INSUFFICIENT_CREDITS | 402 | Insufficient credits. Check the balance and required credits. |
BUDGET_EXCEEDED | 409,429 | Budget limit exceeded. Review usage and the configured budget. |
RATE_LIMITED | 429 | Request rate exceeded. Follow retryable and Retry-After before retrying. |
CAPACITY_EXCEEDED | 429 | Capacity limit exceeded. Reduce the workload or wait for active work to finish. |
PAYLOAD_TOO_LARGE | 413 | Request body too large. Reduce it to the documented limit. |
UNSUPPORTED_MEDIA_TYPE | 415 | Unsupported content type or encoding. Use the documented Content-Type without Content-Encoding. |
UPLOAD_TOO_LARGE | 422 | Uploaded content exceeds its processing limit. Reduce the file size. |
UPLOAD_NOT_VERIFIED | 422 | Upload is incomplete, expired or invalid. Check the upload and verification steps. |
ASSET_KIND_MISMATCH | 422 | Asset type does not match the operation. Select a compatible asset. |
SELECTED_IMAGE_REQUIRED | 422 | Select a valid image before generating video. |
SELECTED_VIDEO_REQUIRED | 422 | Select valid videos for the requested shots before assembly. |
REFERENCE_LIMIT_EXCEEDED | 422 | Too many reference assets. Reduce them to the model limit. |
REFERENCE_IMAGE_REQUIRED | 422 | This model requires a reference image. Add an image or select a text-to-image model. |
INVALID_GENERATION_OPTIONS | 422 | Generation options are invalid. Check the model capabilities. |
PROMPT_REQUIRED | 422 | Provide a generation prompt. |
SCRIPT_TEXT_REQUIRED | 422 | Provide script text before starting this operation. |
SCENES_REQUIRED | 422 | Create scenes before starting this operation. |
VARIANT_NAME_REQUIRED | 422 | Provide a variant name. |
EPISODE_ALREADY_STRUCTURED | 409 | Episode already has shots. Review its existing structure. |
ONE_SCRIPT_PER_PROJECT | 409 | This project supports one script. Use the existing script. |
MULTIPLE_SCRIPTS_REQUIRE_REVIEW | 409 | Multiple scripts need review before continuing. |
NATIVE_CONTENT_ALREADY_EXISTS | 409 | Studio content already exists. Review it before continuing. |
LIVE_PROJECT_REQUIRED | 409 | This operation requires a live project. |
STUDIO_MIGRATION_REQUIRED | 409 | Project needs Studio migration. Contact support. |
UNSUPPORTED_CAPABILITY | 422 | Unsupported operation or profile. Check GET /capabilities. |
CAPABILITY_UNAVAILABLE | 503 | Capability currently unavailable. Check GET /capabilities. |
API_NOT_ACCEPTING | 503 | New requests are paused. Check service availability. |
DEPENDENCY_UNAVAILABLE | 503 | A required service is unavailable. Follow the retry guidance or contact support. |
PRICING_UNAVAILABLE | 503 | Pricing unavailable. A valid quote is required to proceed. |
MEDIA_TOOLS_UNAVAILABLE | 503 | Media processing unavailable. Contact support. |
STORAGE_READ_FAILED | 503 | Could not read the stored asset. Contact support with request_id. |
STORAGE_WRITE_FAILED | 503 | Could not save the asset. Check the result before retrying. |
INTERNAL_ERROR | 500 | Internal error. Follow retry guidance; include request_id when contacting support. |
RESPONSE_CONTRACT_VIOLATION | 500 | Server response validation failed. Contact support with request_id. |
INVALID_EXECUTION_CONTEXT | 500 | Execution context is invalid. Contact support. |
RETRY_TRANSACTION | 503 | Transaction could not complete. Follow the response retry guidance. |
CLAIM_LOST | 409 | Execution ownership changed. Check the current job state. |
PROVIDER_TIMEOUT | 504 | Generation service timed out. Check the existing job before submitting again. |
PROVIDER_TERMINAL_FAILURE | 422 | Generation failed. Review the job result and inputs. |
PROVIDER_RESULT_UNAVAILABLE | 502 | Generation result unavailable. Check the existing job and recovery options. |
INVALID_RESULT | 422,503 | Result failed validation. Review the job or contact support. |
RESULT_TOO_LARGE | 422 | Result exceeds the processing limit. Reduce the requested output. |
EXPORT_TOO_LARGE | 422 | Export exceeds the size limit. Reduce the export selection. |
RECOVERY_BACKOFF | 409 | Existing result recovery is delayed. Check again later; do not resubmit generation. |
VIDEO_RECOVERY_REVIEW_REQUIRED | 503 | The original video task needs scheduled recovery or operator review. Do not resubmit generation. |
RESULT_RECOVERY_REQUIRED | 409,503 | Existing result needs recovery. Check the run recovery options before resubmitting. |
RESULT_NOT_RECOVERABLE | 409 | Result cannot be recovered through this action. Review the run or contact support. |
RECOVERY_CAPACITY_EXCEEDED | 409 | Recovery limit reached. Contact support before further recovery attempts. |
USAGE_RECOVERY_REQUIRED | 503 | Usage needs reconciliation. Contact support; do not resubmit generation blindly. |