> 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/production.md).

# Production

Make the media in Studio, then edit and export it.

### creative\_produce

Produce one concept into finished media (video, carousel or static image) like Studio's Generate button, which picks an actor if none is set. Costs 50 credits plus the media credits Studio charges (about its credit\_range; a key's monthly limit needs room for both); no fee when already produced or producing (started false) or production fails. Takes minutes: returns a job\_id; poll jobs\_get for the Creative, or a failed job whose error names the reason and the creative for creative\_get.

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

#### Input

| Field             | Type   | Required | Description                                                                                                                                                                |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`     | string | Yes      | Campaign id from campaign\_list or campaign\_create.                                                                                                                       |
| `concept_id`      | string | Yes      | Concept id from concept\_list. It must come from a plan run of the last 7 days; concepts from older runs or drafted with draft\_briefs cannot be produced through the API. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                     |

### creative\_get

Read one creative (an approved or produced concept): production status, output URLs, the post package (caption, hashtags, publish status) and its Studio project. For existing text/layout read project\_get, then use slides\_update for image outputs or timeline\_update for video; concept\_draft\_get starts the workflow for a new scripted version, and export\_render makes the updated file.

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

#### Input

| Field         | Type   | Required | Description                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `campaign_id` | string | Yes      | Campaign id from campaign\_list or campaign\_create.                |
| `creative_id` | string | Yes      | Creative id from creative\_list, concept\_list or concept\_approve. |

#### Output

| Field                         | Type             | Description                                                                                                                                                                                                                                       |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display_code`                | string           | Studio's AVA-C### label within this displayed week, with a V suffix for a submitted version.                                                                                                                                                      |
| `root_concept_id`             | string           |                                                                                                                                                                                                                                                   |
| `version_number`              | integer          | Value at least 1.                                                                                                                                                                                                                                 |
| `version_count`               | integer          | Value at least 0.                                                                                                                                                                                                                                 |
| `creative_id`                 | string           |                                                                                                                                                                                                                                                   |
| `concept_id`                  | string           | The concept it was produced from (a brief id).                                                                                                                                                                                                    |
| `campaign_id`                 | string           |                                                                                                                                                                                                                                                   |
| `period_start`                | string           | Plan run day it belongs to (YYYY-MM-DD).                                                                                                                                                                                                          |
| `title`                       | string           |                                                                                                                                                                                                                                                   |
| `hook`                        | string           |                                                                                                                                                                                                                                                   |
| `output_kind`                 | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                                                                                       |
| `status`                      | string           | queued = approved, production not started (creative\_produce starts it); producing; ready = media done; posted = marked posted; failed = production failed or was skipped (see error). One of `queued`, `producing`, `ready`, `posted`, `failed`. |
| `stage`                       | string           | While producing: planning scenes, generating media or rendering the export. One of `planning`, `generating`, `rendering`.                                                                                                                         |
| `outputs`                     | object           | Files the user sees in Studio; empty until ready.                                                                                                                                                                                                 |
| `outputs.video_url`           | string           | Exported video (MP4), for video creatives.                                                                                                                                                                                                        |
| `outputs.image_urls`          | array of strings | Exported images in slide order, for carousel and static creatives.                                                                                                                                                                                |
| `outputs.thumbnail_url`       | string           |                                                                                                                                                                                                                                                   |
| `outputs.partial`             | boolean          | True when only some carousel slides were produced.                                                                                                                                                                                                |
| `post_package`                | object           | Organic campaigns: what to post with it.                                                                                                                                                                                                          |
| `post_package.platform`       | string           | One of `tiktok`, `instagram`.                                                                                                                                                                                                                     |
| `post_package.caption`        | string           | Post caption, ready to paste.                                                                                                                                                                                                                     |
| `post_package.hashtags`       | array of strings |                                                                                                                                                                                                                                                   |
| `post_package.first_comment`  | string           |                                                                                                                                                                                                                                                   |
| `post_package.publish_status` | string           | One of `not_ready`, `ready`, `exported`, `posted`, `failed`.                                                                                                                                                                                      |
| `post_package.posted_at`      | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `post_package.post_url`       | string           | Live post link recorded when it was marked posted.                                                                                                                                                                                                |
| `project_id`                  | string           | Studio project holding its editable timeline; pass to project\_get, project\_edit or export\_render.                                                                                                                                              |
| `estimated_credits`           | number           | Studio's estimate of the media credits to produce it.                                                                                                                                                                                             |
| `error`                       | string           | Short reason, when status is failed.                                                                                                                                                                                                              |
| `studio_url`                  | string           | Ava Studio link to the creative.                                                                                                                                                                                                                  |
| `created_at`                  | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `updated_at`                  | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `next_steps`                  | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                         |

### creative\_list

List a campaign's creatives (approved and produced concepts), newest first, optionally for one plan run or Studio week: status, output URLs and project ids. Call creative\_get for one creative's post package, or creative\_produce on approved concepts not produced yet.

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

#### Input

| Field          | Type    | Required | Description                                                        |
| -------------- | ------- | -------- | ------------------------------------------------------------------ |
| `campaign_id`  | string  | Yes      | Campaign id from campaign\_list or campaign\_create.               |
| `week_start`   | string  |          | All runs in this Monday-Sunday Studio week; omit period\_start.    |
| `period_start` | string  |          | Only creatives from this plan run (YYYY-MM-DD). Omit for all runs. |
| `limit`        | integer |          | Max results (1-100, default 50). Value 1 to 100.                   |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                                                                                       |
| ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                             | string           |                                                                                                                                                                                                                                                   |
| `creatives`                               | array of objects |                                                                                                                                                                                                                                                   |
| `creatives[].display_code`                | string           | Studio's AVA-C### label within this displayed week, with a V suffix for a submitted version.                                                                                                                                                      |
| `creatives[].root_concept_id`             | string           |                                                                                                                                                                                                                                                   |
| `creatives[].version_number`              | integer          | Value at least 1.                                                                                                                                                                                                                                 |
| `creatives[].version_count`               | integer          | Value at least 0.                                                                                                                                                                                                                                 |
| `creatives[].creative_id`                 | string           |                                                                                                                                                                                                                                                   |
| `creatives[].concept_id`                  | string           | The concept it was produced from (a brief id).                                                                                                                                                                                                    |
| `creatives[].campaign_id`                 | string           |                                                                                                                                                                                                                                                   |
| `creatives[].period_start`                | string           | Plan run day it belongs to (YYYY-MM-DD).                                                                                                                                                                                                          |
| `creatives[].title`                       | string           |                                                                                                                                                                                                                                                   |
| `creatives[].hook`                        | string           |                                                                                                                                                                                                                                                   |
| `creatives[].output_kind`                 | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                                                                                       |
| `creatives[].status`                      | string           | queued = approved, production not started (creative\_produce starts it); producing; ready = media done; posted = marked posted; failed = production failed or was skipped (see error). One of `queued`, `producing`, `ready`, `posted`, `failed`. |
| `creatives[].stage`                       | string           | While producing: planning scenes, generating media or rendering the export. One of `planning`, `generating`, `rendering`.                                                                                                                         |
| `creatives[].outputs`                     | object           | Files the user sees in Studio; empty until ready.                                                                                                                                                                                                 |
| `creatives[].outputs.video_url`           | string           | Exported video (MP4), for video creatives.                                                                                                                                                                                                        |
| `creatives[].outputs.image_urls`          | array of strings | Exported images in slide order, for carousel and static creatives.                                                                                                                                                                                |
| `creatives[].outputs.thumbnail_url`       | string           |                                                                                                                                                                                                                                                   |
| `creatives[].outputs.partial`             | boolean          | True when only some carousel slides were produced.                                                                                                                                                                                                |
| `creatives[].post_package`                | object           | Organic campaigns: what to post with it.                                                                                                                                                                                                          |
| `creatives[].post_package.platform`       | string           | One of `tiktok`, `instagram`.                                                                                                                                                                                                                     |
| `creatives[].post_package.caption`        | string           | Post caption, ready to paste.                                                                                                                                                                                                                     |
| `creatives[].post_package.hashtags`       | array of strings |                                                                                                                                                                                                                                                   |
| `creatives[].post_package.first_comment`  | string           |                                                                                                                                                                                                                                                   |
| `creatives[].post_package.publish_status` | string           | One of `not_ready`, `ready`, `exported`, `posted`, `failed`.                                                                                                                                                                                      |
| `creatives[].post_package.posted_at`      | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `creatives[].post_package.post_url`       | string           | Live post link recorded when it was marked posted.                                                                                                                                                                                                |
| `creatives[].project_id`                  | string           | Studio project holding its editable timeline; pass to project\_get, project\_edit or export\_render.                                                                                                                                              |
| `creatives[].estimated_credits`           | number           | Studio's estimate of the media credits to produce it.                                                                                                                                                                                             |
| `creatives[].error`                       | string           | Short reason, when status is failed.                                                                                                                                                                                                              |
| `creatives[].studio_url`                  | string           | Ava Studio link to the creative.                                                                                                                                                                                                                  |
| `creatives[].created_at`                  | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `creatives[].updated_at`                  | string           | ISO-8601 timestamp                                                                                                                                                                                                                                |
| `creatives[].next_steps`                  | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                         |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                         |

### project\_list

List the account's Studio projects (editable videos and image sets), newest first, optionally for one campaign. Call project\_get for a project's scenes and captions.

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

#### Input

| Field         | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `campaign_id` | string  |          | Only this campaign's projects.                   |
| `limit`       | integer |          | Max results (1-100, default 20). Value 1 to 100. |

#### Output

| Field                          | Type             | Description                                                                             |
| ------------------------------ | ---------------- | --------------------------------------------------------------------------------------- |
| `projects`                     | array of objects |                                                                                         |
| `projects[].project_id`        | string           |                                                                                         |
| `projects[].title`             | string           |                                                                                         |
| `projects[].project_type`      | string           | video = a timeline; image = an image set (carousel or static). One of `video`, `image`. |
| `projects[].aspect_ratio`      | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                    |
| `projects[].campaign_id`       | string           |                                                                                         |
| `projects[].brand_id`          | string           |                                                                                         |
| `projects[].status`            | string           | One of `active`, `archived`.                                                            |
| `projects[].generating`        | boolean          | True while some of its scenes are still generating.                                     |
| `projects[].thumbnail_url`     | string           |                                                                                         |
| `projects[].latest_export_url` | string           | Last exported file, when it has been exported.                                          |
| `projects[].studio_url`        | string           | Ava Studio link to the project's editor.                                                |
| `projects[].created_at`        | string           | ISO-8601 timestamp                                                                      |
| `projects[].updated_at`        | string           | ISO-8601 timestamp                                                                      |
| `next_steps`                   | array of strings | Short hints naming the next tool to call.                                               |

### project\_get

Read a Studio project: scenes in timeline order (type, timing, status, caption, selected media and latest generation), every timeline element with its id, the captions and other on-screen text with their position and style, the script lines and the latest export; prompts stay hidden. Read it before project\_edit, timeline\_add or timeline\_remove; call export\_render for a fresh file.

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

#### Input

| Field        | Type   | Required | Description                                                                             |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------- |
| `project_id` | string | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list. |

#### 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.                                                                                                                                                               |

### project\_history

Read a project's saved user and assistant conversation, including reference attachments, when reconnecting or continuing work from another client. Newest messages first with next\_cursor for older pages, excluding internal prompts and tool traces.

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

#### Input

| Field        | Type    | Required | Description                                                                             |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------- |
| `project_id` | string  | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list. |
| `limit`      | integer |          | Max results (1-100, default 30). Value 1 to 100.                                        |
| `cursor`     | string  |          | At most 2000 characters.                                                                |

#### Output

| Field                           | Type             | Description                               |
| ------------------------------- | ---------------- | ----------------------------------------- |
| `project_id`                    | string           |                                           |
| `messages`                      | array of objects |                                           |
| `messages[].message_id`         | string           |                                           |
| `messages[].role`               | string           | One of `user`, `assistant`.               |
| `messages[].text`               | string           |                                           |
| `messages[].sent_at`            | string           |                                           |
| `messages[].thread_id`          | string           |                                           |
| `messages[].attachments`        | array of objects |                                           |
| `messages[].attachments[].type` | string           |                                           |
| `messages[].attachments[].url`  | string           |                                           |
| `messages[].attachments[].name` | string           |                                           |
| `next_cursor`                   | string           |                                           |
| `next_steps`                    | array of strings | Short hints naming the next tool to call. |

### project\_edit

Apply one plain-language edit to a produced project's timeline: retime or trim scenes and b-roll, cut dead air, move captions onto their beat or off a face or the product, resize or move picture-in-picture and split-screen media. It cannot change words, add, remove or regenerate scenes, or touch music and voice. Costs 10 credits plus the AI usage; returns a job\_id, poll jobs\_get, then call export\_render for the edited file.

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

#### Input

| Field             | Type   | Required | Description                                                                                                                                 |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`      | string | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                     |
| `instruction`     | string | Yes      | One edit in plain words, e.g. start the b-roll when she says twenty grams, or move the CTA caption above the product. 1 to 2000 characters. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                      |

### export\_render

Render a Studio project to a downloadable MP4 or image file; watermark:auto (default) follows the owner's plan, watermark:required includes it, and watermark:none requires a paid owner. Costs 10 credits. Free when the project is unchanged since its last export with the same watermark setting; poll jobs\_get for output\_url.

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

#### Input

| Field             | Type   | Required | Description                                                                                                                                      |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id`      | string | Yes      | Studio project id from project\_list, project\_create, creative\_get or creative\_list.                                                          |
| `watermark`       | string |          | Default auto: use the project owner's entitlement; required includes a watermark, none requires a paid owner. One of `auto`, `required`, `none`. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                           |

### broll\_create

Make one 5-second vertical B-roll clip from 1-4 of the brand's images (product photos, app screens or web pages, by media\_id) with a Studio B-roll template; the clip joins the brand's media, analyzed. Costs the media credits Studio charges for it, about 75 (a key with a monthly limit needs room for them). Returns a job\_id (a few minutes); poll jobs\_get, the result is the new media\_item and its project\_id, and media\_credits\_charged what the media cost.

* **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/broll_create`

#### Input

| Field             | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`        | string           | Yes      | Brand id from brand\_list or whoami.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `media_ids`       | array of strings | Yes      | 1-4 of the brand's images (not videos or logos), in order: the clearest product photos, app screens or web pages. 1 to 4 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `template`        | string           | Yes      | Studio's B-roll template; pick one made for what the images show. App screens: tap-through-flow (2+ distinct images, in order): Move between the screens in order, as if someone is using the app; feature-reveal: Start on the whole screen, then settle on one feature; scroll-and-zoom: Scroll the screen while the camera eases in. Web pages: page-walkthrough (2+ distinct images, in order): Move between the supplied pages in order; feature-highlight: Settle on one section of the page and hold there; scroll-through-page: Scroll down the page at reading pace. Product photos: product-showcase: Orbit the product so the whole thing reads; detail-reveal: Open tight on a detail, then pull back to the whole product; natural-interaction: A pair of hands picks the product up and turns it. Graphics and other images: subtle-motion: Keep the composition and add gentle life to it; dynamic-reveal: Open close on a detail, then pull back to the full frame; slow-push-in: One steady push towards the centre of the frame. One of `tap-through-flow`, `feature-reveal`, `scroll-and-zoom`, `page-walkthrough`, `feature-highlight`, `scroll-through-page`, `product-showcase`, `detail-reveal`, `natural-interaction`, `subtle-motion`, `dynamic-reveal`, `slow-push-in`. |
| `notes`           | string           |          | Extra direction added to the template's prompt, in a sentence (keep the label facing the camera); it never replaces the template. At most 500 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `source_type`     | string           |          | What the images show: mobile\_app (phone app screens), website (web pages), physical\_product (product photos), brand\_graphic or other. Overrides Studio's automatic detection of what the images show, like picking the type in Studio; leave it out to let Studio detect it. Use it when broll\_create was refused because the detected type its error names is wrong (e.g. app screens seen as graphics), with a template made for this type. One of `mobile_app`, `website`, `physical_product`, `brand_graphic`, `other`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `idempotency_key` | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
