> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/tools/studio.md).

# Studio

Generate images, video, and audio with any Studio model, and edit projects.

### project\_ask

Run Studio's content-planning agent for a complete original app/product video or a video/photo-carousel clone; start with project\_create/list and pass brief/assets. Costs 10 credits plus AI tokens and Studio media; AI holds grow within balance/budget, media\_credit\_limit bounds estimated media (default 300). Plan with generate:false, media\_credit\_limit:0 (AI billed); after approval reuse the SAME project with generate:true, relay needs\_input and poll jobs\_get; campaign planning uses plan\_run.

* **Permission:** Produce media (`production`)
* **Price:** 10 + AI tokens + Studio media
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/project_ask`

#### Input

| Field                      | Type             | Required | Description                                                                                                                                                                                                                                                                                                                             |
| -------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`               | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                                                                                                                                                                                                 |
| `message`                  | string           | Yes      | 1 to 8000 characters.                                                                                                                                                                                                                                                                                                                   |
| `attachments`              | array of objects |          | At most 10 items.                                                                                                                                                                                                                                                                                                                       |
| `attachments[].type`       | string           | Yes      | One of `image`, `video`, `url`, `carousel`.                                                                                                                                                                                                                                                                                             |
| `attachments[].source`     | object           | Yes      | An image/video file, owned library asset, or public reference link. Use carousel for a TikTok /photo/ post; url for social video links.                                                                                                                                                                                                 |
| `attachments[].source.url` | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                      |
| `attachments[].name`       | string           |          | 1 to 200 characters.                                                                                                                                                                                                                                                                                                                    |
| `generate`                 | boolean          |          | Default `false`.                                                                                                                                                                                                                                                                                                                        |
| `media_credit_limit`       | integer          |          | Maximum estimated media credits to admit in this turn, including preparation (voiceover/reference images) and generation. Counted against a key's monthly budget up front; unused credits are released. Actual provider prices can differ from estimates. 0 allows planning without paid media tools. Value 0 to 100000. Default `300`. |
| `idempotency_key`          | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                  |

### models\_list

List the image, video and audio models Studio offers, optionally of one kind: modes, aspect ratios, durations, resolutions, qualities, reference limits and Studio's credit prices (the API charges the same). Pick a model here before image\_generate, video\_generate, audio\_generate or scene\_generate, then quote the cost with generation\_estimate.

* **Permission:** Any key
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/models_list`

#### Input

| Field  | Type   | Required | Description                                                 |
| ------ | ------ | -------- | ----------------------------------------------------------- |
| `kind` | string |          | Only models of this kind. One of `image`, `video`, `audio`. |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models`                                  | array of objects |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `models[].model`                          | string           | A model id from models\_list. One of `gpt_2_5`, `gpt_2`, `gpt`, `grok_imagine_image_2_0`, `flash_3_1`, `nano_banana_2_lite`, `nano_banana_pro`, `seedream_v5_lite`, `flash_2_5`, `minimax_image_01`, `imagen_4`, `imagen_4_ultra`, `reframe`, `seedream_v5_pro_layerize`, `omni_flash_1_2`, `kling_v4_flash`, `omni_flash_1_1`, `wan_3_0`, `omni_flash`, `seedance_2_5`, `seedance_2_0`, `seedance_2_0_fast`, `seedance_2_0_mini`, `seedance_pro_1_5`, `grok_imagine_video_1_5`, `kling_v3`, `kling_o3`, `veo_3_1`, `veo_3_1_fast`, `sora_2`, `hailuo_standard_2_3`, `flashvsr_upscale`, `veed_video_background_removal`, `eleven_v3`, `lyria`, `eleven_labs_music`, `eleven_labs_effect`, `mmaudio`. |
| `models[].kind`                           | string           | image, video or audio. One of `image`, `video`, `audio`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `models[].label`                          | string           | Studio's name for it, e.g. Kling O3.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `models[].modes`                          | array of strings | Each one of `text_to_image`, `image_edit`, `text_to_video`, `image_to_video`, `first_last_frame`, `reference`, `extend`, `video_edit`, `motion_control`, `multi_shot`, `tts`, `music`, `sound_effect`, `upscale`, `background_removal`, `reframe`, `layerize`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `models[].aspect_ratios`                  | array of strings | Aspect ratios it takes; empty for audio. Each one of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `models[].durations`                      | object           | Durations it makes, for video and timed audio.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `models[].durations.min`                  | number           | Shortest duration, seconds. Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `models[].durations.max`                  | number           | Longest duration, seconds. Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `models[].durations.step`                 | number           | Allowed step between min and max, seconds. Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `models[].durations.values`               | array of numbers | The only allowed durations, when not every step is (Veo 4, 6 or 8).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `models[].resolutions`                    | array of strings | Video: resolutions (pass as resolution). Image: output sizes (pass as image\_size). Empty when there is no choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `models[].qualities`                      | array of strings | Quality tiers (pass as quality); empty when there is no choice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `models[].max_reference_images`           | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `models[].max_reference_videos`           | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `models[].audio_option`                   | boolean          | True when generate\_audio switches its audio on or off.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `models[].price`                          | object           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `models[].price.unit`                     | string           | per\_image: per image made; per\_second: per second of output; flat: per call. One of `per_image`, `per_second`, `flat`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `models[].price.studio_credits_by_option` | object           | Studio's credits per unit, by option: a resolution (720p), a quality (high), a quality at a size (1K\_low), audio\_on / audio\_off, or default. The API charges the same.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `models[].notes`                          | string           | Limits worth knowing, e.g. at most 2 images per call, prompts up to 512 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### generation\_estimate

Quote 1-20 generations at Studio's media credits for the model and settings (what the API charges too), plus the total; video bills on the clip's measured length, which can run a frame long (4 s may bill as 4.04 s). Work priced after the fact is quoted at its most: image\_layerize at 17 layers of a large image (up to 1536×1536 pixels costs half), video\_remove\_background at the duration given (else 60 s). Tell the user the total first; a key with a monthly limit needs room for it.

* **Permission:** Any key
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/generation_estimate`

#### Input

| Field                    | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items`                  | array of objects | Yes      | 1-20 generations to quote, each a model and its settings. 1 to 20 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `items[].model`          | string           | Yes      | A model id from models\_list. One of `gpt_2_5`, `gpt_2`, `gpt`, `grok_imagine_image_2_0`, `flash_3_1`, `nano_banana_2_lite`, `nano_banana_pro`, `seedream_v5_lite`, `flash_2_5`, `minimax_image_01`, `imagen_4`, `imagen_4_ultra`, `reframe`, `seedream_v5_pro_layerize`, `omni_flash_1_2`, `kling_v4_flash`, `omni_flash_1_1`, `wan_3_0`, `omni_flash`, `seedance_2_5`, `seedance_2_0`, `seedance_2_0_fast`, `seedance_2_0_mini`, `seedance_pro_1_5`, `grok_imagine_video_1_5`, `kling_v3`, `kling_o3`, `veo_3_1`, `veo_3_1_fast`, `sora_2`, `hailuo_standard_2_3`, `flashvsr_upscale`, `veed_video_background_removal`, `eleven_v3`, `lyria`, `eleven_labs_music`, `eleven_labs_effect`, `mmaudio`. |
| `items[].mode`           | string           |          | The mode, when it changes the price or the model used (reference, video\_edit, ...). One of `text_to_image`, `image_edit`, `text_to_video`, `image_to_video`, `first_last_frame`, `reference`, `extend`, `video_edit`, `motion_control`, `multi_shot`, `tts`, `music`, `sound_effect`, `upscale`, `background_removal`, `reframe`, `layerize`.                                                                                                                                                                                                                                                                                                                                                        |
| `items[].duration`       | number           |          | Seconds of output: video length, music length, or the video's length for background removal (up to 600). Value 0 to 600.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `items[].resolution`     | string           |          | Video resolution (default 720p); models\_list lists each model's. One of `360p`, `480p`, `720p`, `1080p`, `4k`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `items[].quality`        | string           |          | Quality tier, for the models that price by it (models\_list qualities): GPT Image low to max, Grok Imagine low or medium. One of `low`, `medium`, `high`, `auto`, `xhigh`, `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `items[].image_size`     | string           |          | Image output size, for the models that offer it (models\_list resolutions). One of `1K`, `2K`, `4K`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `items[].count`          | integer          |          | Images per call, or variants of a scene (1-4, default 1). Value 1 to 4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `items[].generate_audio` | boolean          |          | Audio on or off, for models where it changes the price (default on).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

#### Output

| Field                   | Type             | Description                                                                                                            |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `items`                 | array of objects | One quote per input item, in order.                                                                                    |
| `items[].media_credits` | number           | Studio's media credits for it, charged by the generation pipeline: all it costs through the API too. Value at least 0. |
| `total`                 | number           | Sum of the items' media credits. Value at least 0.                                                                     |
| `next_steps`            | array of strings | Short hints naming the next tool to call.                                                                              |

### image\_generate

Generate 1-4 images with any Studio image model from a prompt, optionally editing or steering with reference images; they are saved to the user's Studio library, and with save\_to\_brand\_id to that brand's media. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation\_estimate first. Returns a job\_id; poll jobs\_get for the images' urls and library\_asset\_ids.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/image_generate`

#### Input

| Field              | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`           | string           | Yes      | What to make, in plain words (up to 4000 characters; Kling O3 takes 512). 1 to 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `model`            | string           | Yes      | Image model; models\_list has each one's limits and prices. gpt\_2\_5 (GPT Image 2.5: precise prompts, legible text and edits from up to 9 reference images; quality low to max); gpt\_2 (GPT Image 2: strong text and edits from up to 10 reference images; quality low, medium, high or auto); gpt (GPT Image 1: the earlier GPT model; edits from 1 reference image); grok\_imagine\_image\_2\_0 (Grok Imagine 2.0: fast photoreal images at 1K or 2K, quality low or medium; up to 3 reference images); flash\_3\_1 (Nano Banana 2: consistent products and people at 1K, 2K or 4K; up to 4 reference images); nano\_banana\_2\_lite (Nano Banana 2 Lite: a cheaper, faster Nano Banana 2; up to 4 reference images); nano\_banana\_pro (Nano Banana Pro: Gemini's highest-fidelity images at 1K, 2K or 4K; at most 2 per call, up to 4 reference images); seedream\_v5\_lite (Seedream v5 Lite: low-cost detailed images and edits from up to 10 reference images); flash\_2\_5 (Nano Banana: low-cost images and edits from up to 4 reference images); minimax\_image\_01 (MiniMax Image 01: the cheapest; edits from 1 reference image); imagen\_4 (Imagen 4: Google's text-to-image model; no reference images); imagen\_4\_ultra (Imagen 4 Ultra: Imagen 4 at higher fidelity; no reference images). One of `gpt_2_5`, `gpt_2`, `gpt`, `grok_imagine_image_2_0`, `flash_3_1`, `nano_banana_2_lite`, `nano_banana_pro`, `seedream_v5_lite`, `flash_2_5`, `minimax_image_01`, `imagen_4`, `imagen_4_ultra`. |
| `aspect_ratio`     | string           |          | Default 9:16; models\_list lists each model's. One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `quality`          | string           |          | Quality tier, for the models that price by it (models\_list qualities): GPT Image low to max, Grok Imagine low or medium. One of `low`, `medium`, `high`, `auto`, `xhigh`, `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `image_size`       | string           |          | Image output size, for the models that offer it (models\_list resolutions). One of `1K`, `2K`, `4K`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `count`            | integer          |          | Images to make (1-4, default 1; nano\_banana\_pro at most 2). Value 1 to 4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `reference_images` | array of objects |          | Images to edit or follow (image\_edit): each {url}, {media\_id} or {library\_asset\_id}; at most the model's max\_reference\_images. 1 to 10 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `background`       | string           |          | GPT Image models: the background (transparent needs png or webp). One of `auto`, `transparent`, `opaque`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `output_format`    | string           |          | GPT Image models: the file format (default png). One of `png`, `jpeg`, `webp`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `save_to_brand_id` | string           |          | Also add each result to this brand's media and analyze it, so productions can use it; the result then carries its media\_id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `idempotency_key`  | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### video\_generate

Generate a video from a prompt and optional reference media, saved to the user's Studio library and optionally save\_to\_brand\_id; Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation\_estimate first. After the user approves the estimate, call this tool to start generation; prompts alone do not generate. Returns a job\_id (minutes); poll jobs\_get and share the video URL.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/video_generate`

#### Input

| Field                        | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`                     | string           | Yes      | What to make, in plain words (up to 4000 characters; Kling O3 takes 512). 1 to 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `model`                      | string           | Yes      | Video model; models\_list has each one's limits and prices. omni\_flash\_1\_2 (Omni Flash 1.2: text, image (optional end frame), references (10 images, 3 videos up to 15s), edit and native extend; 3-15s, 360p to 4k, 16:9 or 9:16. End-frame interpolation and extension cap at 10s); kling\_v4\_flash (Kling 4.0 Flash: text, start image, references (10 images, 5 videos totaling 20s), edit and extend; 3-20s at 720p, native audio, no end frame. Video inputs also count toward the price); omni\_flash\_1\_1 (Omni Flash 1.1: text, image (optional end frame), reference (images, up to 3 videos of 3 s or less), video edit and extend; 3-10 s, 360p to 4k, 16:9 or 9:16); wan\_3\_0 (Wan 3.0: text, image (optional end frame) and reference video; native audio, 2-30 s at 480p-1080p. Up to 10 images, 5 videos and 5 audio clips; video/audio inputs each total at most 15 s); omni\_flash (Omni Flash: text, image, reference, video edit and extend; 3-10 s at 720p); seedance\_2\_5 (Seedance 2.5: text, image, reference and extend; 4-30 s, 480p to 1080p); seedance\_2\_0 (Seedance 2.0: text, image, reference and extend; 4-15 s, 480p to 4k); seedance\_2\_0\_fast (Seedance 2.0 Fast: a cheaper Seedance 2.0 at 480p or 720p; 4-15 s); seedance\_2\_0\_mini (Seedance 2.0 Mini: the cheapest Seedance, 480p or 720p; 4-15 s); seedance\_pro\_1\_5 (Seedance Pro 1.5: text, image and extend; 4-12 s up to 1080p); grok\_imagine\_video\_1\_5 (Grok Imagine 1.5: text, image and reference (up to 7 images); 1-15 s at 480p or 720p); kling\_v3 (Kling 3.0: text, image (start and end frame), extend and motion control (an image plus a reference video); 3-15 s at 1080p, audio on or off); kling\_o3 (Kling O3: text, image, reference (up to 7 images, or reference videos), video edit, extend and multi-shot; 3-15 s, audio on or off; prompts up to 512 characters); veo\_3\_1 (Veo 3.1: native audio; text, image, first and last frame, reference (8 s) and extend (720p); 4, 6 or 8 s, 720p to 4k, 16:9 or 9:16); veo\_3\_1\_fast (Veo 3.1 Fast: a cheaper Veo 3.1; text, image, first and last frame and extend); sora\_2 (Sora 2: text, image and extend; 4-20 s in steps of 4, 720p, 16:9 or 9:16); hailuo\_standard\_2\_3 (Hailuo 2.3 Standard: text, image and extend; 6 or 10 s at 1080p). One of `omni_flash_1_2`, `kling_v4_flash`, `omni_flash_1_1`, `wan_3_0`, `omni_flash`, `seedance_2_5`, `seedance_2_0`, `seedance_2_0_fast`, `seedance_2_0_mini`, `seedance_pro_1_5`, `grok_imagine_video_1_5`, `kling_v3`, `kling_o3`, `veo_3_1`, `veo_3_1_fast`, `sora_2`, `hailuo_standard_2_3`. |
| `mode`                       | string           |          | text\_to\_video; image\_to\_video (start\_image, optional end\_image where the model takes one); first\_last\_frame (start\_image and end\_image); reference (reference\_images, reference\_videos or reference\_audio steer the shot); extend (continue extend\_from\_video); video\_edit (edit reference\_videos\[0] by the prompt); motion\_control (start\_image moved like motion\_reference\_video); multi\_shot (multi\_prompt). Default: image\_to\_video with a start\_image, reference with reference media, else text\_to\_video. models\_list says which modes each model has. One of `text_to_video`, `image_to_video`, `first_last_frame`, `reference`, `extend`, `video_edit`, `motion_control`, `multi_shot`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `aspect_ratio`               | string           |          | Default 9:16; models\_list lists each model's. One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `duration`                   | number           |          | Seconds (default: the model's shortest); models\_list lists each model's range. Value 1 to 30.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `resolution`                 | string           |          | Video resolution (default 720p); models\_list lists each model's. One of `360p`, `480p`, `720p`, `1080p`, `4k`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `generate_audio`             | boolean          |          | Native audio on or off, for models with audio\_option (default on).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `start_image`                | object           |          | First frame: image\_to\_video, first\_last\_frame and motion\_control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `start_image.url`            | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `end_image`                  | object           |          | Last frame: first\_last\_frame, or image\_to\_video on models that take an end frame.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `end_image.url`              | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `reference_images`           | array of objects |          | Images that steer the look (reference mode): each {url}, {media\_id} or {library\_asset\_id}; up to 10, and at most the model's limit in models\_list. 1 to 10 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `reference_videos`           | array of objects |          | Videos: references in reference mode, or the video to edit in video\_edit: each {url}, {media\_id} or {library\_asset\_id}; up to 5, and at most the model's limit in models\_list. 1 to 5 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `reference_audio`            | array of objects |          | Audio references, for the models that take them in reference mode: each {url}, {media\_id} or {library\_asset\_id}; up to 5, and at most the model's limit in models\_list. 1 to 5 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `motion_reference_video`     | object           |          | motion\_control: the video whose motion start\_image follows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `motion_reference_video.url` | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `extend_from_video`          | object           |          | extend: the video to continue.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `extend_from_video.url`      | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `multi_prompt`               | array of objects |          | multi\_shot: 2-6 shots, each a prompt and seconds, in order. 2 to 6 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `multi_prompt[].prompt`      | string           | Yes      | 1 to 512 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `multi_prompt[].duration`    | number           | Yes      | Seconds. Value 1 to 15.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `save_to_brand_id`           | string           |          | Also add each result to this brand's media and analyze it, so productions can use it; the result then carries its media\_id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `idempotency_key`            | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### audio\_generate

Generate a voiceover from a script in a voice from voices\_list, music from a prompt, or a sound effect from a prompt (or matched to a video with mmaudio); it is saved to the user's Studio library, ready for timeline\_add. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation\_estimate first. Returns a job\_id; poll jobs\_get for the audio.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/audio_generate`

#### Input

| Field             | Type   | Required | Description                                                                                                                                                                                                                                                                   |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`            | string | Yes      | voiceover: speech from a script (eleven\_v3, voice\_id); music (lyria or eleven\_labs\_music); sound\_effect (eleven\_labs\_effect, or mmaudio from a video). One of `voiceover`, `music`, `sound_effect`.                                                                    |
| `text`            | string | Yes      | voiceover: the script, exactly as it should be spoken; music and sound\_effect: what it should sound like. 1 to 3000 characters.                                                                                                                                              |
| `voice_id`        | string |          | voiceover: a voice\_id from voices\_list (default: Studio's default voice).                                                                                                                                                                                                   |
| `model`           | string |          | voiceover: eleven\_v3 (the only one); music: lyria (default, fixed length) or eleven\_labs\_music (duration\_sec); sound\_effect: eleven\_labs\_effect (default) or mmaudio (needs video). One of `eleven_v3`, `lyria`, `eleven_labs_music`, `eleven_labs_effect`, `mmaudio`. |
| `duration_sec`    | number |          | Length in seconds: eleven\_labs\_music 10-30; sound effects up to 22. Default: the model's own. Value 0.5 to 30.                                                                                                                                                              |
| `video`           | object |          | mmaudio: the video to make sound effects for.                                                                                                                                                                                                                                 |
| `video.url`       | string | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                            |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                        |

### voices\_list

List the voices Studio offers for voiceovers (name, gender, accent, description and a preview link); with query, also search ElevenLabs' community voices. Pass a voice\_id to audio\_generate.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/voices_list`

#### Input

| Field   | Type   | Required | Description                                                                           |
| ------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `query` | string |          | Words to search community voices by, e.g. deep british narrator. 1 to 100 characters. |

#### Output

| Field                  | Type             | Description                                                                                                          |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `voices`               | array of objects |                                                                                                                      |
| `voices[].voice_id`    | string           | Pass to audio\_generate voice\_id.                                                                                   |
| `voices[].name`        | string           |                                                                                                                      |
| `voices[].gender`      | string           |                                                                                                                      |
| `voices[].accent`      | string           |                                                                                                                      |
| `voices[].description` | string           |                                                                                                                      |
| `voices[].preview_url` | string           | A short sample to listen to.                                                                                         |
| `voices[].source`      | string           | studio: Studio's own voices; community: ElevenLabs' shared library (found with query). One of `studio`, `community`. |
| `next_steps`           | array of strings | Short hints naming the next tool to call.                                                                            |

### video\_upscale

Upscale a video (a link, brand media or a library asset) with FlashVSR; the result is saved to the user's Studio library. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation\_estimate. Returns a job\_id; poll jobs\_get for the video.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/video_upscale`

#### Input

| Field             | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `video`           | object | Yes      | The video to upscale.                                                                              |
| `video.url`       | string | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.             |

### video\_remove\_background

Cut the subject out of a video (a link, brand media or a library asset) onto a transparent background; the result is saved to the user's Studio library. Costs Studio's price for the model and settings (the same media credits as in Ava Studio), per second of video: quote it with generation\_estimate. Returns a job\_id; poll jobs\_get for the video and its alpha mask.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/video_remove_background`

#### Input

| Field             | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `video`           | object | Yes      | The video to cut the subject out of.                                                               |
| `video.url`       | string | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.             |

### image\_reframe

Reframe an image to another aspect ratio, extending the scene past its edges; the result is saved to the user's Studio library. Costs Studio's price for the model and settings (the same media credits as in Ava Studio): quote it with generation\_estimate. Returns a job\_id; poll jobs\_get for the image.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/image_reframe`

#### Input

| Field             | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `image`           | object | Yes      | The image to reframe.                                                                              |
| `image.url`       | string | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters. |
| `aspect_ratio`    | string | Yes      | The aspect ratio to reframe to. One of `9:16`, `4:5`, `1:1`, `16:9`.                               |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.             |

### image\_layerize

Split an image into editable transparent layers (subject, text, background); the layers are saved to the user's Studio library. Costs Studio's price for the model and settings (the same media credits as in Ava Studio), per layer made (2-17): generation\_estimate quotes all 17 at the large-image price, the most it can cost (a key with a monthly limit needs room for that); an image up to 1536×1536 pixels costs half. Returns a job\_id; poll jobs\_get for the layers.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/image_layerize`

#### Input

| Field             | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `image`           | object | Yes      | The image to split into layers.                                                                    |
| `image.url`       | string | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.             |

### project\_create

Create a Studio project; use project\_type:image for a carousel or static post, video (default) for a video. Use project\_ask on the same project\_id through planning and approved generation, then export\_render (images/ZIP for image projects, MP4 for video). Linking campaign\_id organizes the project; campaign planning uses plan\_run/creative\_produce, and manual editing uses scene\_generate/timeline tools.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/project_create`

#### Input

| Field             | Type   | Required | Description                                                                                                                                                                                                 |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`           | string | Yes      | 1 to 200 characters.                                                                                                                                                                                        |
| `aspect_ratio`    | string | Yes      | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                        |
| `project_type`    | string |          | image = carousel slides or a single static image; video = a video timeline (default). Choose image when the user asks for a carousel, even though its slides have timeline timing. One of `video`, `image`. |
| `brand_id`        | string |          | The brand it is for.                                                                                                                                                                                        |
| `campaign_id`     | string |          | The user's selected campaign to keep this project under; reuse its id. Linking a project does not run the campaign planner (plan\_run).                                                                     |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                      |

#### Output

| Field                                      | Type             | Description                                                                                                                                                                                             |
| ------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                               | string           |                                                                                                                                                                                                         |
| `title`                                    | string           |                                                                                                                                                                                                         |
| `project_type`                             | string           | video = a timeline; image = an image set (carousel or static). One of `video`, `image`.                                                                                                                 |
| `aspect_ratio`                             | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                    |
| `campaign_id`                              | string           |                                                                                                                                                                                                         |
| `brand_id`                                 | string           |                                                                                                                                                                                                         |
| `status`                                   | string           | One of `active`, `archived`.                                                                                                                                                                            |
| `generating`                               | boolean          | True while some of its scenes are still generating.                                                                                                                                                     |
| `thumbnail_url`                            | string           |                                                                                                                                                                                                         |
| `latest_export_url`                        | string           | Last exported file, when it has been exported.                                                                                                                                                          |
| `studio_url`                               | string           | Ava Studio link to the project's editor.                                                                                                                                                                |
| `created_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                      |
| `updated_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                      |
| `duration_sec`                             | number           | Timeline length, for video projects. Value at least 0.                                                                                                                                                  |
| `scenes`                                   | array of objects |                                                                                                                                                                                                         |
| `scenes[].index`                           | integer          | 1-based position on the timeline (slide number in an image project). Value at least 1.                                                                                                                  |
| `scenes[].scene_id`                        | string           |                                                                                                                                                                                                         |
| `scenes[].media_type`                      | string           | One of `video`, `image`.                                                                                                                                                                                |
| `scenes[].start_sec`                       | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].duration_sec`                    | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].status`                          | string           | ready = has media on the timeline; generating; failed = its last generation failed; empty = no media yet. One of `ready`, `generating`, `failed`, `empty`.                                              |
| `scenes[].caption`                         | string           | The captions (speech timed to the voiceover) shown over this scene, if any.                                                                                                                             |
| `scenes[].on_screen_text`                  | string           | Titles, labels and other text shown over this scene apart from its captions, if any.                                                                                                                    |
| `scenes[].thumbnail_url`                   | string           |                                                                                                                                                                                                         |
| `scenes[].media`                           | array of objects | The scene's selected media on the timeline (video or image, and its own audio).                                                                                                                         |
| `scenes[].media[].element_id`              | string           | Its element on the timeline, when it is on it; pass to timeline\_remove.                                                                                                                                |
| `scenes[].media[].url`                     | string           |                                                                                                                                                                                                         |
| `scenes[].media[].kind`                    | string           | One of `video`, `image`, `audio`.                                                                                                                                                                       |
| `scenes[].media[].duration_sec`            | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].latest_generation`               | object           | The scene's most recent generation (scene\_generate or Studio), when it has one.                                                                                                                        |
| `scenes[].latest_generation.generation_id` | string           |                                                                                                                                                                                                         |
| `scenes[].latest_generation.status`        | string           | One of `queued`, `generating`, `ready`, `failed`.                                                                                                                                                       |
| `captions`                                 | array of objects | Captions timed to speech, in time order; other on-screen text is under texts. In an image project, each slide's text.                                                                                   |
| `captions[].text`                          | string           |                                                                                                                                                                                                         |
| `captions[].start_sec`                     | number           | Value at least 0.                                                                                                                                                                                       |
| `captions[].end_sec`                       | number           | Value at least 0.                                                                                                                                                                                       |
| `captions[].scene_index`                   | integer          | Scene it sits over, when it sits over one. Value at least 1.                                                                                                                                            |
| `captions[].element_id`                    | string           | Its text element; pass to timeline\_update or timeline\_remove.                                                                                                                                         |
| `captions[].position`                      | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `captions[].position.x`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `captions[].position.y`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `captions[].position.w`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `captions[].position.h`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `captions[].style`                         | object           | Its look as stored.                                                                                                                                                                                     |
| `captions[].style.font_family`             | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `captions[].style.font_size`               | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `captions[].style.color`                   | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `captions[].style.background_color`        | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `captions[].style.bold`                    | boolean          |                                                                                                                                                                                                         |
| `captions[].style.align`                   | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `texts`                                    | array of objects | On-screen text that is not a caption (titles, labels, hooks, calls to action), in time order, with its position and style.                                                                              |
| `texts[].text`                             | string           |                                                                                                                                                                                                         |
| `texts[].start_sec`                        | number           | Value at least 0.                                                                                                                                                                                       |
| `texts[].end_sec`                          | number           | Value at least 0.                                                                                                                                                                                       |
| `texts[].scene_index`                      | integer          | Scene it sits over, when it sits over one. Value at least 1.                                                                                                                                            |
| `texts[].element_id`                       | string           | Its text element; pass to timeline\_update or timeline\_remove.                                                                                                                                         |
| `texts[].position`                         | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `texts[].position.x`                       | number           | Value 0 to 1.                                                                                                                                                                                           |
| `texts[].position.y`                       | number           | Value 0 to 1.                                                                                                                                                                                           |
| `texts[].position.w`                       | number           | Value at most 1.                                                                                                                                                                                        |
| `texts[].position.h`                       | number           | Value at most 1.                                                                                                                                                                                        |
| `texts[].style`                            | object           | Its look as stored.                                                                                                                                                                                     |
| `texts[].style.font_family`                | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `texts[].style.font_size`                  | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `texts[].style.color`                      | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `texts[].style.background_color`           | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `texts[].style.bold`                       | boolean          |                                                                                                                                                                                                         |
| `texts[].style.align`                      | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `script`                                   | array of objects | The spoken and on-screen lines the project is built from.                                                                                                                                               |
| `script[].id`                              | string           | Script tag, e.g. Hook, Body\_1, Cta.                                                                                                                                                                    |
| `script[].text`                            | string           |                                                                                                                                                                                                         |
| `elements`                                 | array of objects | Every element on the timeline in start order (scene media, overlays, audio, text) with its id, for timeline\_add and timeline\_remove.                                                                  |
| `elements[].element_id`                    | string           |                                                                                                                                                                                                         |
| `elements[].kind`                          | string           | One of `video`, `image`, `audio`, `text`.                                                                                                                                                               |
| `elements[].track`                         | string           | visual: the main scene track; overlay: on top of it; audio; text. One of `visual`, `audio`, `overlay`, `text`.                                                                                          |
| `elements[].start_sec`                     | number           | Value at least 0.                                                                                                                                                                                       |
| `elements[].duration_sec`                  | number           | Value at least 0.                                                                                                                                                                                       |
| `elements[].scene_id`                      | string           | The scene it belongs to, when it is a scene's media.                                                                                                                                                    |
| `elements[].url`                           | string           | The media file, for video, image and audio.                                                                                                                                                             |
| `elements[].text`                          | string           | The words, for text.                                                                                                                                                                                    |
| `elements[].position`                      | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `elements[].position.x`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `elements[].position.y`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `elements[].position.w`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `elements[].position.h`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `elements[].style`                         | object           | text: its look as stored.                                                                                                                                                                               |
| `elements[].style.font_family`             | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `elements[].style.font_size`               | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `elements[].style.color`                   | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `elements[].style.background_color`        | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `elements[].style.bold`                    | boolean          |                                                                                                                                                                                                         |
| `elements[].style.align`                   | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `elements[].caption`                       | boolean          | text: true for a caption timed to speech (captions\_generate, Ava's productions); project\_get lists those under captions and other text under texts.                                                   |
| `elements[].volume`                        | number           | audio and video: the volume its sound plays at, 0-1. A video's sound is its linked audio element (listed too, with sound\_of): one sound, played once; a video without one is silent (0). Value 0 to 1. |
| `elements[].muted`                         | boolean          | audio and video: true when it plays no sound (volume 0).                                                                                                                                                |
| `elements[].sound_of`                      | string           | audio: the video element whose own sound this is. It moves and trims with that video, and the video's volume and muted are this sound's: it plays once, not twice.                                      |
| `revision`                                 | string           | Changes whenever the project is saved; pass it as expected\_revision to timeline\_add or timeline\_remove to edit only this version.                                                                    |
| `next_steps`                               | array of strings | Short hints naming the next tool to call.                                                                                                                                                               |

### template\_list

List Studio's video templates, optionally for one use case or matching words in the title: title, use case, aspect ratio and preview. Read one with template\_get for its variables and price, then make a project with project\_from\_template.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/template_list`

#### Input

| Field      | Type    | Required | Description                                                            |
| ---------- | ------- | -------- | ---------------------------------------------------------------------- |
| `query`    | string  |          | Words to match in the title or use case. 1 to 200 characters.          |
| `use_case` | string  |          | One of use\_cases from an earlier template\_list. 1 to 100 characters. |
| `limit`    | integer |          | Max results (1-100, default 20). Value 1 to 100.                       |
| `cursor`   | string  |          | next\_cursor from the previous page. 1 to 200 characters.              |

#### Output

| Field                       | Type             | Description                                                |
| --------------------------- | ---------------- | ---------------------------------------------------------- |
| `templates`                 | array of objects |                                                            |
| `templates[].template_id`   | string           |                                                            |
| `templates[].title`         | string           |                                                            |
| `templates[].use_case`      | string           |                                                            |
| `templates[].aspect_ratio`  | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                       |
| `templates[].preview_url`   | string           | A preview video of the template.                           |
| `templates[].thumbnail_url` | string           |                                                            |
| `templates[].duration_sec`  | number           | Value at least 0.                                          |
| `templates[].scene_count`   | integer          | Value at least 0.                                          |
| `use_cases`                 | array of strings | Use cases to filter by.                                    |
| `next_cursor`               | string           | Pass as cursor for the next page; absent on the last page. |
| `next_steps`                | array of strings | Short hints naming the next tool to call.                  |

### template\_get

Read one Studio template: the variables to fill (text or media, required or with a default), each scene's variables and whether changing them generates it again, what stays fixed (music, voiceover, an actor without a variable), its preview and the quote for making a project from it (Studio's media credits). Pass the variables to project\_from\_template.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/template_get`

#### Input

| Field         | Type   | Required | Description                      |
| ------------- | ------ | -------- | -------------------------------- |
| `template_id` | string | Yes      | Template id from template\_list. |

#### Output

| Field                     | Type             | Description                                                                                                                                                                                                                                 |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template_id`             | string           |                                                                                                                                                                                                                                             |
| `title`                   | string           |                                                                                                                                                                                                                                             |
| `use_case`                | string           |                                                                                                                                                                                                                                             |
| `aspect_ratio`            | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                                                        |
| `preview_url`             | string           | A preview video of the template.                                                                                                                                                                                                            |
| `thumbnail_url`           | string           |                                                                                                                                                                                                                                             |
| `duration_sec`            | number           | Value at least 0.                                                                                                                                                                                                                           |
| `scene_count`             | integer          | Value at least 0.                                                                                                                                                                                                                           |
| `description`             | string           |                                                                                                                                                                                                                                             |
| `variables`               | array of objects |                                                                                                                                                                                                                                             |
| `variables[].name`        | string           | The key to fill in project\_from\_template's variables, e.g. Hook.                                                                                                                                                                          |
| `variables[].kind`        | string           | text takes a string; image and video take {url}, {media\_id} or {library\_asset\_id}. One of `text`, `image`, `video`.                                                                                                                      |
| `variables[].required`    | boolean          | True when the template has no default for it.                                                                                                                                                                                               |
| `variables[].default`     | string           | What it holds when you leave it out (text, or a media link).                                                                                                                                                                                |
| `variables[].description` | string           |                                                                                                                                                                                                                                             |
| `scenes`                  | array of objects | Each scene: the variables it depends on and whether changing them generates it again.                                                                                                                                                       |
| `scenes[].index`          | integer          | 1-based, in the template's scene order. Value at least 1.                                                                                                                                                                                   |
| `scenes[].scene_id`       | string           |                                                                                                                                                                                                                                             |
| `scenes[].media_type`     | string           | One of `video`, `image`.                                                                                                                                                                                                                    |
| `scenes[].start_sec`      | number           | Value at least 0.                                                                                                                                                                                                                           |
| `scenes[].duration_sec`   | number           | Value at least 0.                                                                                                                                                                                                                           |
| `scenes[].depends_on`     | array of strings | Variables (names) that change this scene: the ones its media was generated from, or a media variable whose file replaces it. Empty: it stays exactly as in the template.                                                                    |
| `scenes[].regenerates`    | boolean          | true: its media is generated again (charged at its model's price) when one of depends\_on gets a new value, or always when the template has no media for it. false: it is kept, or only swapped for a media variable's file.                |
| `fixed`                   | array of objects | What no variable changes: it stays as in the template in every project made from it.                                                                                                                                                        |
| `fixed[].kind`            | string           | One of `video`, `image`, `audio`, `text`.                                                                                                                                                                                                   |
| `fixed[].role`            | string           | scene: a scene's media (its actor, setting and action as generated); overlay: other video or image; music, voiceover, sound\_effect or other audio; text. One of `scene`, `overlay`, `music`, `voiceover`, `sound_effect`, `audio`, `text`. |
| `fixed[].label`           | string           | Its name in the template, or the words of fixed text.                                                                                                                                                                                       |
| `fixed[].scene_index`     | integer          | The scene, for a scene's media. Value at least 1.                                                                                                                                                                                           |
| `fixed[].start_sec`       | number           | Value at least 0.                                                                                                                                                                                                                           |
| `fixed[].duration_sec`    | number           | Value at least 0.                                                                                                                                                                                                                           |
| `estimate`                | object           | What project\_from\_template costs with this template: Studio's media credits for it.                                                                                                                                                       |
| `estimate.media_credits`  | number           | Studio's media credits for it, charged by the generation pipeline: all it costs through the API too. Value at least 0.                                                                                                                      |
| `next_steps`              | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                   |

### project\_from\_template

Make a project from a Studio template with your variables: only what depends on them changes (a scene generated from a variable you change is generated again, media variables swap in your file, text variables fill in); the rest stays as in the template (template\_get: each scene's depends\_on, and what is fixed). Costs Studio's price for the template: its 10-credit base fee plus each scene it generates at its model's price; template\_get quotes it. Returns a job\_id; poll jobs\_get.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/project_from_template`

#### Input

| Field             | Type   | Required | Description                                                                                                                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template_id`     | string | Yes      | Template id from template\_list.                                                                                                                          |
| `variables`       | object |          | Values by variable name from template\_get: a string for text, {url}, {media\_id} or {library\_asset\_id} for image and video. Required ones must be set. |
| `title`           | string |          | The new project's title (default: the template's). 1 to 200 characters.                                                                                   |
| `brand_id`        | string |          | The brand it is for.                                                                                                                                      |
| `campaign_id`     | string |          | A campaign to file it under.                                                                                                                              |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                    |

### scene\_generate

Generate 1-4 variants of one scene of a project with any image or video model, into a scene from project\_get or a new one after the last. Costs Studio's price for the model and settings (the same media credits as in Ava Studio), per variant: quote it with generation\_estimate (count = variant\_count). Returns a job\_id; jobs\_get gives the variants and, for a scene without media, where the first ready one went (placement); swap in another with scene\_select\_variant.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/scene_generate`

#### Input

| Field                        | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id`                 | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scene_id`                   | string           |          | The scene to generate into, from project\_get; omit to append a new scene.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `prompt`                     | string           | Yes      | What to make, in plain words (up to 4000 characters; Kling O3 takes 512). 1 to 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `model`                      | string           | Yes      | An image or a video model; models\_list has each one's limits and prices. Image: gpt\_2\_5 (GPT Image 2.5: precise prompts, legible text and edits from up to 9 reference images; quality low to max); gpt\_2 (GPT Image 2: strong text and edits from up to 10 reference images; quality low, medium, high or auto); gpt (GPT Image 1: the earlier GPT model; edits from 1 reference image); grok\_imagine\_image\_2\_0 (Grok Imagine 2.0: fast photoreal images at 1K or 2K, quality low or medium; up to 3 reference images); flash\_3\_1 (Nano Banana 2: consistent products and people at 1K, 2K or 4K; up to 4 reference images); nano\_banana\_2\_lite (Nano Banana 2 Lite: a cheaper, faster Nano Banana 2; up to 4 reference images); nano\_banana\_pro (Nano Banana Pro: Gemini's highest-fidelity images at 1K, 2K or 4K; at most 2 per call, up to 4 reference images); seedream\_v5\_lite (Seedream v5 Lite: low-cost detailed images and edits from up to 10 reference images); flash\_2\_5 (Nano Banana: low-cost images and edits from up to 4 reference images); minimax\_image\_01 (MiniMax Image 01: the cheapest; edits from 1 reference image); imagen\_4 (Imagen 4: Google's text-to-image model; no reference images); imagen\_4\_ultra (Imagen 4 Ultra: Imagen 4 at higher fidelity; no reference images). Video: omni\_flash\_1\_2 (Omni Flash 1.2: text, image (optional end frame), references (10 images, 3 videos up to 15s), edit and native extend; 3-15s, 360p to 4k, 16:9 or 9:16. End-frame interpolation and extension cap at 10s); kling\_v4\_flash (Kling 4.0 Flash: text, start image, references (10 images, 5 videos totaling 20s), edit and extend; 3-20s at 720p, native audio, no end frame. Video inputs also count toward the price); omni\_flash\_1\_1 (Omni Flash 1.1: text, image (optional end frame), reference (images, up to 3 videos of 3 s or less), video edit and extend; 3-10 s, 360p to 4k, 16:9 or 9:16); wan\_3\_0 (Wan 3.0: text, image (optional end frame) and reference video; native audio, 2-30 s at 480p-1080p. Up to 10 images, 5 videos and 5 audio clips; video/audio inputs each total at most 15 s); omni\_flash (Omni Flash: text, image, reference, video edit and extend; 3-10 s at 720p); seedance\_2\_5 (Seedance 2.5: text, image, reference and extend; 4-30 s, 480p to 1080p); seedance\_2\_0 (Seedance 2.0: text, image, reference and extend; 4-15 s, 480p to 4k); seedance\_2\_0\_fast (Seedance 2.0 Fast: a cheaper Seedance 2.0 at 480p or 720p; 4-15 s); seedance\_2\_0\_mini (Seedance 2.0 Mini: the cheapest Seedance, 480p or 720p; 4-15 s); seedance\_pro\_1\_5 (Seedance Pro 1.5: text, image and extend; 4-12 s up to 1080p); grok\_imagine\_video\_1\_5 (Grok Imagine 1.5: text, image and reference (up to 7 images); 1-15 s at 480p or 720p); kling\_v3 (Kling 3.0: text, image (start and end frame), extend and motion control (an image plus a reference video); 3-15 s at 1080p, audio on or off); kling\_o3 (Kling O3: text, image, reference (up to 7 images, or reference videos), video edit, extend and multi-shot; 3-15 s, audio on or off; prompts up to 512 characters); veo\_3\_1 (Veo 3.1: native audio; text, image, first and last frame, reference (8 s) and extend (720p); 4, 6 or 8 s, 720p to 4k, 16:9 or 9:16); veo\_3\_1\_fast (Veo 3.1 Fast: a cheaper Veo 3.1; text, image, first and last frame and extend); sora\_2 (Sora 2: text, image and extend; 4-20 s in steps of 4, 720p, 16:9 or 9:16); hailuo\_standard\_2\_3 (Hailuo 2.3 Standard: text, image and extend; 6 or 10 s at 1080p). One of `gpt_2_5`, `gpt_2`, `gpt`, `grok_imagine_image_2_0`, `flash_3_1`, `nano_banana_2_lite`, `nano_banana_pro`, `seedream_v5_lite`, `flash_2_5`, `minimax_image_01`, `imagen_4`, `imagen_4_ultra`, `omni_flash_1_2`, `kling_v4_flash`, `omni_flash_1_1`, `wan_3_0`, `omni_flash`, `seedance_2_5`, `seedance_2_0`, `seedance_2_0_fast`, `seedance_2_0_mini`, `seedance_pro_1_5`, `grok_imagine_video_1_5`, `kling_v3`, `kling_o3`, `veo_3_1`, `veo_3_1_fast`, `sora_2`, `hailuo_standard_2_3`. |
| `mode`                       | string           |          | Image scenes: text\_to\_image, or image\_edit with reference\_images. Video scenes: the video\_generate modes. Default from the media given, as video\_generate. One of `text_to_image`, `image_edit`, `text_to_video`, `image_to_video`, `first_last_frame`, `reference`, `extend`, `video_edit`, `motion_control`, `multi_shot`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `aspect_ratio`               | string           |          | Default 9:16; models\_list lists each model's. One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `duration`                   | number           |          | Seconds (default: the model's shortest); models\_list lists each model's range. Value 1 to 30.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `resolution`                 | string           |          | Video resolution (default 720p); models\_list lists each model's. One of `360p`, `480p`, `720p`, `1080p`, `4k`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `generate_audio`             | boolean          |          | Native audio on or off, for models with audio\_option (default on).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `start_image`                | object           |          | First frame: image\_to\_video, first\_last\_frame and motion\_control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `start_image.url`            | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `end_image`                  | object           |          | Last frame: first\_last\_frame, or image\_to\_video on models that take an end frame.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `end_image.url`              | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `reference_images`           | array of objects |          | Images to edit or follow (image\_edit), or that steer a video (reference): each {url}, {media\_id} or {library\_asset\_id}; at most the model's limit. 1 to 10 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `reference_videos`           | array of objects |          | Videos: references in reference mode, or the video to edit in video\_edit: each {url}, {media\_id} or {library\_asset\_id}; up to 5, and at most the model's limit in models\_list. 1 to 5 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `reference_audio`            | array of objects |          | Audio references, for the models that take them in reference mode: each {url}, {media\_id} or {library\_asset\_id}; up to 5, and at most the model's limit in models\_list. 1 to 5 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `motion_reference_video`     | object           |          | motion\_control: the video whose motion start\_image follows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `motion_reference_video.url` | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `extend_from_video`          | object           |          | extend: the video to continue.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `extend_from_video.url`      | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `multi_prompt`               | array of objects |          | multi\_shot: 2-6 shots, each a prompt and seconds, in order. 2 to 6 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `multi_prompt[].prompt`      | string           | Yes      | 1 to 512 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `multi_prompt[].duration`    | number           | Yes      | Seconds. Value 1 to 15.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `variant_count`              | integer          |          | Variants to make (1-4, default 1); each is charged. Value 1 to 4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `quality`                    | string           |          | Quality tier, for the models that price by it (models\_list qualities): GPT Image low to max, Grok Imagine low or medium. One of `low`, `medium`, `high`, `auto`, `xhigh`, `max`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `image_size`                 | string           |          | Image output size, for the models that offer it (models\_list resolutions). One of `1K`, `2K`, `4K`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `idempotency_key`            | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### scene\_select\_variant

Put one of a scene's generated variants on the timeline, as picking it in Studio does; returns the scene with its media. The generation and variant ids come from scene\_generate's result.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/scene_select_variant`

#### Input

| Field             | Type   | Required | Description                                                                             |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `project_id`      | string | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list. |
| `scene_id`        | string | Yes      | Scene id from project\_get or scene\_generate.                                          |
| `generation_id`   | string | Yes      | Generation id from scene\_generate.                                                     |
| `variant_id`      | string | Yes      | Variant id from scene\_generate.                                                        |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.  |

#### Output

| Field                                   | Type             | Description                                                                                                                                                |
| --------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                            | string           |                                                                                                                                                            |
| `scene`                                 | object           | The scene with the chosen variant's media.                                                                                                                 |
| `scene.index`                           | integer          | 1-based position on the timeline (slide number in an image project). Value at least 1.                                                                     |
| `scene.scene_id`                        | string           |                                                                                                                                                            |
| `scene.media_type`                      | string           | One of `video`, `image`.                                                                                                                                   |
| `scene.start_sec`                       | number           | Value at least 0.                                                                                                                                          |
| `scene.duration_sec`                    | number           | Value at least 0.                                                                                                                                          |
| `scene.status`                          | string           | ready = has media on the timeline; generating; failed = its last generation failed; empty = no media yet. One of `ready`, `generating`, `failed`, `empty`. |
| `scene.caption`                         | string           | The captions (speech timed to the voiceover) shown over this scene, if any.                                                                                |
| `scene.on_screen_text`                  | string           | Titles, labels and other text shown over this scene apart from its captions, if any.                                                                       |
| `scene.thumbnail_url`                   | string           |                                                                                                                                                            |
| `scene.media`                           | array of objects | The scene's selected media on the timeline (video or image, and its own audio).                                                                            |
| `scene.media[].element_id`              | string           | Its element on the timeline, when it is on it; pass to timeline\_remove.                                                                                   |
| `scene.media[].url`                     | string           |                                                                                                                                                            |
| `scene.media[].kind`                    | string           | One of `video`, `image`, `audio`.                                                                                                                          |
| `scene.media[].duration_sec`            | number           | Value at least 0.                                                                                                                                          |
| `scene.latest_generation`               | object           | The scene's most recent generation (scene\_generate or Studio), when it has one.                                                                           |
| `scene.latest_generation.generation_id` | string           |                                                                                                                                                            |
| `scene.latest_generation.status`        | string           | One of `queued`, `generating`, `ready`, `failed`.                                                                                                          |
| `next_steps`                            | array of strings | Short hints naming the next tool to call.                                                                                                                  |

### timeline\_add

Add 1-20 items to a project's timeline in one change: video, image or audio from a link, brand media or the library, or text, each at a start time with an optional duration, track, position and style. Returns the new elements with their ids; check the result with project\_get and render it with export\_render.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/timeline_add`

#### Input

| Field                            | Type             | Required | Description                                                                                                                                                                                                    |
| -------------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                     | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                                                                        |
| `items`                          | array of objects | Yes      | 1-20 items to add, all in one change. 1 to 20 items.                                                                                                                                                           |
| `items[].kind`                   | string           | Yes      | One of `video`, `image`, `audio`, `text`.                                                                                                                                                                      |
| `items[].source`                 | object           |          | video, image and audio: the file ({url}, {media\_id} or {library\_asset\_id}).                                                                                                                                 |
| `items[].source.url`             | string           | Yes      | Public https link to the file, or a media\_url from library\_upload\_url. At most 2048 characters.                                                                                                             |
| `items[].text`                   | string           |          | text: the words to show. 1 to 500 characters.                                                                                                                                                                  |
| `items[].start_sec`              | number           | Yes      | When it starts on the timeline, seconds. Value 0 to 600.                                                                                                                                                       |
| `items[].duration_sec`           | number           |          | How long it shows (default: the media's own length; 3 s for images and text). Value at most 600.                                                                                                               |
| `items[].track`                  | string           |          | visual: the main track; overlay: on top of it (picture-in-picture, B-roll cutaways); audio. Default: audio for audio, visual for video and image; text has its own track. One of `visual`, `audio`, `overlay`. |
| `items[].position`               | object           |          | Where a video, image or text sits (default: video and image fill the frame; text in the top safe area, clear of the captions).                                                                                 |
| `items[].position.x`             | number           | Yes      | Value 0 to 1.                                                                                                                                                                                                  |
| `items[].position.y`             | number           | Yes      | Value 0 to 1.                                                                                                                                                                                                  |
| `items[].position.w`             | number           | Yes      | Value at most 1.                                                                                                                                                                                               |
| `items[].position.h`             | number           | Yes      | Value at most 1.                                                                                                                                                                                               |
| `items[].style`                  | object           |          | Text only: font, size, colors, weight and alignment.                                                                                                                                                           |
| `items[].style.font_family`      | string           |          | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                          |
| `items[].style.font_size`        | number           |          | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                         |
| `items[].style.color`            | string           |          | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                              |
| `items[].style.background_color` | string           |          | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                       |
| `items[].style.bold`             | boolean          |          |                                                                                                                                                                                                                |
| `items[].style.align`            | string           |          | One of `left`, `center`, `right`.                                                                                                                                                                              |
| `items[].include_audio`          | boolean          |          | video: also add the clip's own sound, as a linked audio element (default false: the clip plays silent, so it never plays over the voiceover).                                                                  |
| `items[].volume`                 | number           |          | audio: its volume (default 1); video: its own sound's volume, with include\_audio (default 1). Value 0 to 1.                                                                                                   |
| `expected_revision`              | string           |          | The project's revision from project\_get; when set and the project was saved since, the call fails with invalid\_input and changes nothing. 1 to 64 characters.                                                |
| `idempotency_key`                | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                         |

#### Output

| Field                            | Type             | Description                                                                                                                                                                                             |
| -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                     | string           |                                                                                                                                                                                                         |
| `added`                          | array of objects | The new elements, in input order.                                                                                                                                                                       |
| `added[].element_id`             | string           |                                                                                                                                                                                                         |
| `added[].kind`                   | string           | One of `video`, `image`, `audio`, `text`.                                                                                                                                                               |
| `added[].track`                  | string           | visual: the main scene track; overlay: on top of it; audio; text. One of `visual`, `audio`, `overlay`, `text`.                                                                                          |
| `added[].start_sec`              | number           | Value at least 0.                                                                                                                                                                                       |
| `added[].duration_sec`           | number           | Value at least 0.                                                                                                                                                                                       |
| `added[].scene_id`               | string           | The scene it belongs to, when it is a scene's media.                                                                                                                                                    |
| `added[].url`                    | string           | The media file, for video, image and audio.                                                                                                                                                             |
| `added[].text`                   | string           | The words, for text.                                                                                                                                                                                    |
| `added[].position`               | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `added[].position.x`             | number           | Value 0 to 1.                                                                                                                                                                                           |
| `added[].position.y`             | number           | Value 0 to 1.                                                                                                                                                                                           |
| `added[].position.w`             | number           | Value at most 1.                                                                                                                                                                                        |
| `added[].position.h`             | number           | Value at most 1.                                                                                                                                                                                        |
| `added[].style`                  | object           | text: its look as stored.                                                                                                                                                                               |
| `added[].style.font_family`      | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `added[].style.font_size`        | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `added[].style.color`            | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `added[].style.background_color` | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `added[].style.bold`             | boolean          |                                                                                                                                                                                                         |
| `added[].style.align`            | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `added[].caption`                | boolean          | text: true for a caption timed to speech (captions\_generate, Ava's productions); project\_get lists those under captions and other text under texts.                                                   |
| `added[].volume`                 | number           | audio and video: the volume its sound plays at, 0-1. A video's sound is its linked audio element (listed too, with sound\_of): one sound, played once; a video without one is silent (0). Value 0 to 1. |
| `added[].muted`                  | boolean          | audio and video: true when it plays no sound (volume 0).                                                                                                                                                |
| `added[].sound_of`               | string           | audio: the video element whose own sound this is. It moves and trims with that video, and the video's volume and muted are this sound's: it plays once, not twice.                                      |
| `revision`                       | string           | The project's revision after the change.                                                                                                                                                                |
| `next_steps`                     | array of strings | Short hints naming the next tool to call.                                                                                                                                                               |

### timeline\_update

Change 1-20 elements of a project's timeline in one change: move, retime or trim them, set volume or mute, reposition a video, image or text, restyle text, or move a clip between the main and overlay tracks. A video's own sound moves and trims with it. Returns the changed elements with their style; element ids come from project\_get or timeline\_add.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/timeline_update`

#### Input

| Field                            | Type             | Required | Description                                                                                                                                                     |
| -------------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                     | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                         |
| `items`                          | array of objects | Yes      | 1-20 changes, all in one change, each naming one element. 1 to 20 items.                                                                                        |
| `items[].text`                   | string           |          | Replace this on-screen text only; does not change spoken audio. At most 10000 characters.                                                                       |
| `items[].element_id`             | string           | Yes      | The element to change, from project\_get or timeline\_add.                                                                                                      |
| `items[].start_sec`              | number           |          | Move it to start here. A video's own sound moves with it. Value 0 to 600.                                                                                       |
| `items[].duration_sec`           | number           |          | Show it this long; a video or audio at most what is left of its file after trim\_start\_sec. Value at most 600.                                                 |
| `items[].trim_start_sec`         | number           |          | video and audio: skip this much of the file's start; the element keeps its start and length, shortened when the file has less left. Value 0 to 600.             |
| `items[].trim_end_sec`           | number           |          | video and audio: stop this much before the file's end (sets the length; not with duration\_sec). Value 0 to 600.                                                |
| `items[].volume`                 | number           |          | audio, or a video with its own sound (added with include\_audio): its volume. Value 0 to 1.                                                                     |
| `items[].muted`                  | boolean          |          | audio, or a video with its own sound: true silences it; false brings it back at volume, else as it was before.                                                  |
| `items[].position`               | object           |          | video, image or text: where it sits (media keeps its proportions inside the box).                                                                               |
| `items[].position.x`             | number           | Yes      | Value 0 to 1.                                                                                                                                                   |
| `items[].position.y`             | number           | Yes      | Value 0 to 1.                                                                                                                                                   |
| `items[].position.w`             | number           | Yes      | Value at most 1.                                                                                                                                                |
| `items[].position.h`             | number           | Yes      | Value at most 1.                                                                                                                                                |
| `items[].style`                  | object           |          | text: its look; fields you leave out stay as they are.                                                                                                          |
| `items[].style.font_family`      | string           |          | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                           |
| `items[].style.font_size`        | number           |          | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                          |
| `items[].style.color`            | string           |          | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                               |
| `items[].style.background_color` | string           |          | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                        |
| `items[].style.bold`             | boolean          |          |                                                                                                                                                                 |
| `items[].style.align`            | string           |          | One of `left`, `center`, `right`.                                                                                                                               |
| `items[].track`                  | string           |          | video or image: the main track, or overlay (on top of it, a free overlay track). One of `visual`, `overlay`.                                                    |
| `expected_revision`              | string           |          | The project's revision from project\_get; when set and the project was saved since, the call fails with invalid\_input and changes nothing. 1 to 64 characters. |
| `idempotency_key`                | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                          |

#### Output

| Field                              | Type             | Description                                                                                                                                                                                             |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                       | string           |                                                                                                                                                                                                         |
| `updated`                          | array of objects | The changed elements as they are now, in input order, then any video's own sound that changed with it.                                                                                                  |
| `updated[].element_id`             | string           |                                                                                                                                                                                                         |
| `updated[].kind`                   | string           | One of `video`, `image`, `audio`, `text`.                                                                                                                                                               |
| `updated[].track`                  | string           | visual: the main scene track; overlay: on top of it; audio; text. One of `visual`, `audio`, `overlay`, `text`.                                                                                          |
| `updated[].start_sec`              | number           | Value at least 0.                                                                                                                                                                                       |
| `updated[].duration_sec`           | number           | Value at least 0.                                                                                                                                                                                       |
| `updated[].scene_id`               | string           | The scene it belongs to, when it is a scene's media.                                                                                                                                                    |
| `updated[].url`                    | string           | The media file, for video, image and audio.                                                                                                                                                             |
| `updated[].text`                   | string           | The words, for text.                                                                                                                                                                                    |
| `updated[].position`               | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `updated[].position.x`             | number           | Value 0 to 1.                                                                                                                                                                                           |
| `updated[].position.y`             | number           | Value 0 to 1.                                                                                                                                                                                           |
| `updated[].position.w`             | number           | Value at most 1.                                                                                                                                                                                        |
| `updated[].position.h`             | number           | Value at most 1.                                                                                                                                                                                        |
| `updated[].style`                  | object           | text: its look as stored.                                                                                                                                                                               |
| `updated[].style.font_family`      | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `updated[].style.font_size`        | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `updated[].style.color`            | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `updated[].style.background_color` | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `updated[].style.bold`             | boolean          |                                                                                                                                                                                                         |
| `updated[].style.align`            | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `updated[].caption`                | boolean          | text: true for a caption timed to speech (captions\_generate, Ava's productions); project\_get lists those under captions and other text under texts.                                                   |
| `updated[].volume`                 | number           | audio and video: the volume its sound plays at, 0-1. A video's sound is its linked audio element (listed too, with sound\_of): one sound, played once; a video without one is silent (0). Value 0 to 1. |
| `updated[].muted`                  | boolean          | audio and video: true when it plays no sound (volume 0).                                                                                                                                                |
| `updated[].sound_of`               | string           | audio: the video element whose own sound this is. It moves and trims with that video, and the video's volume and muted are this sound's: it plays once, not twice.                                      |
| `revision`                         | string           | The project's revision after the change.                                                                                                                                                                |
| `next_steps`                       | array of strings | Short hints naming the next tool to call.                                                                                                                                                               |

### timeline\_remove

Remove 1-50 elements from a project's timeline by element\_id (from project\_get or timeline\_add) in one change; ids not on it come back in not\_found.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/timeline_remove`

#### Input

| Field               | Type             | Required | Description                                                                                                                                                     |
| ------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`        | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                         |
| `element_ids`       | array of strings | Yes      | 1-50 element ids from project\_get or timeline\_add. 1 to 50 items.                                                                                             |
| `expected_revision` | string           |          | The project's revision from project\_get; when set and the project was saved since, the call fails with invalid\_input and changes nothing. 1 to 64 characters. |
| `idempotency_key`   | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                          |

#### Output

| Field        | Type             | Description                               |
| ------------ | ---------------- | ----------------------------------------- |
| `project_id` | string           |                                           |
| `removed`    | array of strings | Element ids taken off the timeline.       |
| `not_found`  | array of strings | Ids not on the timeline.                  |
| `revision`   | string           | The project's revision after the change.  |
| `next_steps` | array of strings | Short hints naming the next tool to call. |

### captions\_generate

Add timed captions to a project from its voiceover, or from the audio element given, as Studio's auto captions do. Costs Studio's price for caption timing: 2 credits per started minute of audio, at least 2 (a 2-minute voiceover costs 4). Returns a job\_id; poll jobs\_get for the captions and media\_credits\_charged.

* **Permission:** Produce media (`production`)
* **Price:** Studio price
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/captions_generate`

#### Input

| Field              | Type   | Required | Description                                                                             |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------- |
| `project_id`       | string | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list. |
| `audio_element_id` | string |          | The audio element to caption, from project\_get (default: the voiceover).               |
| `idempotency_key`  | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.  |

### library\_list

List the user's Studio media library, newest first, optionally by kind or origin (generated or uploaded): each asset's library\_asset\_id, url, kind and length. Pass {library\_asset\_id} to any media input, such as timeline\_add's source or video\_generate's start\_image.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/library_list`

#### Input

| Field    | Type    | Required | Description                                                                                                           |
| -------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `kind`   | string  |          | Only images, videos or audio. One of `image`, `video`, `audio`.                                                       |
| `origin` | string  |          | Only media made in Studio or the API (generated), or files the user added (uploaded). One of `generated`, `uploaded`. |
| `limit`  | integer |          | Max results (1-100, default 20). Value 1 to 100.                                                                      |
| `cursor` | string  |          | next\_cursor from the previous page. 1 to 200 characters.                                                             |

#### Output

| Field                       | Type             | Description                                                                                                                                                           |
| --------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assets`                    | array of objects |                                                                                                                                                                       |
| `assets[].library_asset_id` | string           | Pass {library\_asset\_id} to any media input.                                                                                                                         |
| `assets[].kind`             | string           | One of `image`, `video`, `audio`.                                                                                                                                     |
| `assets[].url`              | string           |                                                                                                                                                                       |
| `assets[].thumbnail_url`    | string           |                                                                                                                                                                       |
| `assets[].name`             | string           |                                                                                                                                                                       |
| `assets[].origin`           | string           | generated: made in Studio or through the API (older rows are told by their model or storage folder); uploaded: a file the user added. One of `generated`, `uploaded`. |
| `assets[].aspect_ratio`     | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                  |
| `assets[].duration_sec`     | number           | Value at least 0.                                                                                                                                                     |
| `assets[].created_at`       | string           | ISO-8601 timestamp                                                                                                                                                    |
| `next_cursor`               | string           | Pass as cursor for the next page; absent on the last page.                                                                                                            |
| `next_steps`                | array of strings | Short hints naming the next tool to call.                                                                                                                             |

### library\_add

Import 1-10 media files: ChatGPT attachments in files (Ava downloads them; no PUT), or public URLs/completed uploads in items. Links are copied into Ava's storage, uploads stay where they are, and other video codecs are converted to an H.264 MP4 copy. Poll jobs\_get for library\_asset\_id and failed; use {library\_asset\_id} in video\_generate, image\_generate or project\_ask.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/library_add`

#### Input

| Field                  | Type             | Required | Description                                                                                                           |
| ---------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `items`                | array of objects |          | Public links or completed uploads to import. 1 to 10 items.                                                           |
| `items[].url`          | string           | Yes      | Public https link to an image, video or audio file, or media\_url from library\_upload\_url. At most 2048 characters. |
| `items[].name`         | string           |          | A name to show in the library (default: the file's). 1 to 200 characters.                                             |
| `files`                | array of objects |          | ChatGPT attachments to copy into Ava. ChatGPT supplies the file objects. 1 to 10 items.                               |
| `files[].download_url` | string           | Yes      | Temporary download URL supplied by ChatGPT; Ava copies the file before it expires. At most 2048 characters.           |
| `files[].file_id`      | string           | Yes      | The attachment's ChatGPT file ID. 1 to 512 characters.                                                                |
| `files[].mime_type`    | string           |          | Optional media type supplied by ChatGPT; Ava validates the file itself. At most 255 characters.                       |
| `files[].file_name`    | string           |          | Optional original file name. 1 to 255 characters.                                                                     |
| `idempotency_key`      | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                |

### library\_upload\_url

For clients that can PUT bytes, get a presigned link to upload one local image (JPEG, PNG or WebP, up to 50 MB), video (MP4 or MOV, up to 500 MB) or audio file (MP3, WAV or M4A, up to 9.2 MB): PUT the bytes to upload\_url with exactly the returned headers before expires\_at (15 minutes). Then pass media\_url to library\_add or a media input as {url}; an unused upload\_url contains no file. For ChatGPT attachments use library\_add files instead.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/library_upload_url`

#### Input

| Field          | Type    | Required | Description                                                                                                                                                                                                                                                                                                    |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`     | string  | Yes      | The file's name, such as voiceover.mp3. 1 to 255 characters.                                                                                                                                                                                                                                                   |
| `content_type` | string  | Yes      | The file's type: image/jpeg, image/png or image/webp (up to 50 MB); video/mp4 or video/quicktime (.mov, up to 500 MB); audio/mpeg (.mp3), audio/wav or audio/mp4 (.m4a, up to 9.2 MB). One of `image/jpeg`, `image/png`, `image/webp`, `video/mp4`, `video/quicktime`, `audio/mpeg`, `audio/wav`, `audio/mp4`. |
| `size_bytes`   | integer | Yes      | File size in bytes: images up to 50 MB (52428800), videos up to 500 MB (524288000), audio up to 9600000. Value 1 to 524288000.                                                                                                                                                                                 |

#### Output

| Field        | Type             | Description                                                                                               |
| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `upload_url` | string           | Presigned link: PUT the raw file bytes here. Never send your API key to it.                               |
| `method`     | "PUT"            |                                                                                                           |
| `headers`    | object           | Send exactly these headers with the PUT (Content-Type and any signed ones).                               |
| `media_url`  | string           | Where the file lives once uploaded: pass it to library\_add as an item url, or to a media input as {url}. |
| `expires_at` | string           | The upload link stops working at this time (15 minutes after the call).                                   |
| `next_steps` | array of strings | Short hints naming the next tool to call.                                                                 |

### slides\_update

Edit a carousel or static-image project's on-slide text, text styles, positions or slide order without generating images. Read project\_get first: items use element ids, slide\_order is the complete scene\_id order, and expected\_revision prevents stale saves. Call export\_render for updated images/ZIP; baked-in text needs a separately approved targeted image edit.

* **Permission:** Produce media (`production`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/slides_update`

#### Input

| Field                            | Type             | Required | Description                                                                                                                                                     |
| -------------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                     | string           | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                                         |
| `items`                          | array of objects |          | 1 to 100 items.                                                                                                                                                 |
| `items[].element_id`             | string           | Yes      |                                                                                                                                                                 |
| `items[].text`                   | string           |          | Replace this on-slide text only; no image generation. At most 10000 characters.                                                                                 |
| `items[].style`                  | object           |          | Text only: font, size, colors, weight and alignment.                                                                                                            |
| `items[].style.font_family`      | string           |          | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                           |
| `items[].style.font_size`        | number           |          | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                          |
| `items[].style.color`            | string           |          | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                               |
| `items[].style.background_color` | string           |          | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                        |
| `items[].style.bold`             | boolean          |          |                                                                                                                                                                 |
| `items[].style.align`            | string           |          | One of `left`, `center`, `right`.                                                                                                                               |
| `items[].position`               | object           |          | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                            |
| `items[].position.x`             | number           | Yes      | Value 0 to 1.                                                                                                                                                   |
| `items[].position.y`             | number           | Yes      | Value 0 to 1.                                                                                                                                                   |
| `items[].position.w`             | number           | Yes      | Value at most 1.                                                                                                                                                |
| `items[].position.h`             | number           | Yes      | Value at most 1.                                                                                                                                                |
| `slide_order`                    | array of strings |          | 1 to 100 items.                                                                                                                                                 |
| `expected_revision`              | string           | Yes      | The project's revision from project\_get; when set and the project was saved since, the call fails with invalid\_input and changes nothing. 1 to 64 characters. |
| `idempotency_key`                | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                          |

#### Output

| Field                                      | Type             | Description                                                                                                                                                                                             |
| ------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`                               | string           |                                                                                                                                                                                                         |
| `title`                                    | string           |                                                                                                                                                                                                         |
| `project_type`                             | string           | video = a timeline; image = an image set (carousel or static). One of `video`, `image`.                                                                                                                 |
| `aspect_ratio`                             | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                                                    |
| `campaign_id`                              | string           |                                                                                                                                                                                                         |
| `brand_id`                                 | string           |                                                                                                                                                                                                         |
| `status`                                   | string           | One of `active`, `archived`.                                                                                                                                                                            |
| `generating`                               | boolean          | True while some of its scenes are still generating.                                                                                                                                                     |
| `thumbnail_url`                            | string           |                                                                                                                                                                                                         |
| `latest_export_url`                        | string           | Last exported file, when it has been exported.                                                                                                                                                          |
| `studio_url`                               | string           | Ava Studio link to the project's editor.                                                                                                                                                                |
| `created_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                      |
| `updated_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                      |
| `duration_sec`                             | number           | Timeline length, for video projects. Value at least 0.                                                                                                                                                  |
| `scenes`                                   | array of objects |                                                                                                                                                                                                         |
| `scenes[].index`                           | integer          | 1-based position on the timeline (slide number in an image project). Value at least 1.                                                                                                                  |
| `scenes[].scene_id`                        | string           |                                                                                                                                                                                                         |
| `scenes[].media_type`                      | string           | One of `video`, `image`.                                                                                                                                                                                |
| `scenes[].start_sec`                       | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].duration_sec`                    | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].status`                          | string           | ready = has media on the timeline; generating; failed = its last generation failed; empty = no media yet. One of `ready`, `generating`, `failed`, `empty`.                                              |
| `scenes[].caption`                         | string           | The captions (speech timed to the voiceover) shown over this scene, if any.                                                                                                                             |
| `scenes[].on_screen_text`                  | string           | Titles, labels and other text shown over this scene apart from its captions, if any.                                                                                                                    |
| `scenes[].thumbnail_url`                   | string           |                                                                                                                                                                                                         |
| `scenes[].media`                           | array of objects | The scene's selected media on the timeline (video or image, and its own audio).                                                                                                                         |
| `scenes[].media[].element_id`              | string           | Its element on the timeline, when it is on it; pass to timeline\_remove.                                                                                                                                |
| `scenes[].media[].url`                     | string           |                                                                                                                                                                                                         |
| `scenes[].media[].kind`                    | string           | One of `video`, `image`, `audio`.                                                                                                                                                                       |
| `scenes[].media[].duration_sec`            | number           | Value at least 0.                                                                                                                                                                                       |
| `scenes[].latest_generation`               | object           | The scene's most recent generation (scene\_generate or Studio), when it has one.                                                                                                                        |
| `scenes[].latest_generation.generation_id` | string           |                                                                                                                                                                                                         |
| `scenes[].latest_generation.status`        | string           | One of `queued`, `generating`, `ready`, `failed`.                                                                                                                                                       |
| `captions`                                 | array of objects | Captions timed to speech, in time order; other on-screen text is under texts. In an image project, each slide's text.                                                                                   |
| `captions[].text`                          | string           |                                                                                                                                                                                                         |
| `captions[].start_sec`                     | number           | Value at least 0.                                                                                                                                                                                       |
| `captions[].end_sec`                       | number           | Value at least 0.                                                                                                                                                                                       |
| `captions[].scene_index`                   | integer          | Scene it sits over, when it sits over one. Value at least 1.                                                                                                                                            |
| `captions[].element_id`                    | string           | Its text element; pass to timeline\_update or timeline\_remove.                                                                                                                                         |
| `captions[].position`                      | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `captions[].position.x`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `captions[].position.y`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `captions[].position.w`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `captions[].position.h`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `captions[].style`                         | object           | Its look as stored.                                                                                                                                                                                     |
| `captions[].style.font_family`             | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `captions[].style.font_size`               | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `captions[].style.color`                   | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `captions[].style.background_color`        | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `captions[].style.bold`                    | boolean          |                                                                                                                                                                                                         |
| `captions[].style.align`                   | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `texts`                                    | array of objects | On-screen text that is not a caption (titles, labels, hooks, calls to action), in time order, with its position and style.                                                                              |
| `texts[].text`                             | string           |                                                                                                                                                                                                         |
| `texts[].start_sec`                        | number           | Value at least 0.                                                                                                                                                                                       |
| `texts[].end_sec`                          | number           | Value at least 0.                                                                                                                                                                                       |
| `texts[].scene_index`                      | integer          | Scene it sits over, when it sits over one. Value at least 1.                                                                                                                                            |
| `texts[].element_id`                       | string           | Its text element; pass to timeline\_update or timeline\_remove.                                                                                                                                         |
| `texts[].position`                         | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `texts[].position.x`                       | number           | Value 0 to 1.                                                                                                                                                                                           |
| `texts[].position.y`                       | number           | Value 0 to 1.                                                                                                                                                                                           |
| `texts[].position.w`                       | number           | Value at most 1.                                                                                                                                                                                        |
| `texts[].position.h`                       | number           | Value at most 1.                                                                                                                                                                                        |
| `texts[].style`                            | object           | Its look as stored.                                                                                                                                                                                     |
| `texts[].style.font_family`                | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `texts[].style.font_size`                  | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `texts[].style.color`                      | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `texts[].style.background_color`           | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `texts[].style.bold`                       | boolean          |                                                                                                                                                                                                         |
| `texts[].style.align`                      | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `script`                                   | array of objects | The spoken and on-screen lines the project is built from.                                                                                                                                               |
| `script[].id`                              | string           | Script tag, e.g. Hook, Body\_1, Cta.                                                                                                                                                                    |
| `script[].text`                            | string           |                                                                                                                                                                                                         |
| `elements`                                 | array of objects | Every element on the timeline in start order (scene media, overlays, audio, text) with its id, for timeline\_add and timeline\_remove.                                                                  |
| `elements[].element_id`                    | string           |                                                                                                                                                                                                         |
| `elements[].kind`                          | string           | One of `video`, `image`, `audio`, `text`.                                                                                                                                                               |
| `elements[].track`                         | string           | visual: the main scene track; overlay: on top of it; audio; text. One of `visual`, `audio`, `overlay`, `text`.                                                                                          |
| `elements[].start_sec`                     | number           | Value at least 0.                                                                                                                                                                                       |
| `elements[].duration_sec`                  | number           | Value at least 0.                                                                                                                                                                                       |
| `elements[].scene_id`                      | string           | The scene it belongs to, when it is a scene's media.                                                                                                                                                    |
| `elements[].url`                           | string           | The media file, for video, image and audio.                                                                                                                                                             |
| `elements[].text`                          | string           | The words, for text.                                                                                                                                                                                    |
| `elements[].position`                      | object           | x, y: the top-left corner; w, h: width and height; all fractions of the frame (0-1).                                                                                                                    |
| `elements[].position.x`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `elements[].position.y`                    | number           | Value 0 to 1.                                                                                                                                                                                           |
| `elements[].position.w`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `elements[].position.h`                    | number           | Value at most 1.                                                                                                                                                                                        |
| `elements[].style`                         | object           | text: its look as stored.                                                                                                                                                                               |
| `elements[].style.font_family`             | string           | A font Studio offers, e.g. Inter or TikTok Sans. 1 to 100 characters.                                                                                                                                   |
| `elements[].style.font_size`               | number           | Size in pixels at 1080 px frame width. Value 8 to 300.                                                                                                                                                  |
| `elements[].style.color`                   | string           | Text color, #RRGGBB (#RRGGBBAA when see-through).                                                                                                                                                       |
| `elements[].style.background_color`        | string           | A box behind the words, #RRGGBB or #RRGGBBAA; absent when there is none.                                                                                                                                |
| `elements[].style.bold`                    | boolean          |                                                                                                                                                                                                         |
| `elements[].style.align`                   | string           | One of `left`, `center`, `right`.                                                                                                                                                                       |
| `elements[].caption`                       | boolean          | text: true for a caption timed to speech (captions\_generate, Ava's productions); project\_get lists those under captions and other text under texts.                                                   |
| `elements[].volume`                        | number           | audio and video: the volume its sound plays at, 0-1. A video's sound is its linked audio element (listed too, with sound\_of): one sound, played once; a video without one is silent (0). Value 0 to 1. |
| `elements[].muted`                         | boolean          | audio and video: true when it plays no sound (volume 0).                                                                                                                                                |
| `elements[].sound_of`                      | string           | audio: the video element whose own sound this is. It moves and trims with that video, and the video's volume and muted are this sound's: it plays once, not twice.                                      |
| `revision`                                 | string           | Changes whenever the project is saved; pass it as expected\_revision to timeline\_add or timeline\_remove to edit only this version.                                                                    |
| `next_steps`                               | array of strings | Short hints naming the next tool to call.                                                                                                                                                               |
