# Studio productions

> Parameters of every studio production tool, from free plan validation to frame, motion, voice and soundtrack generation, with scopes and quotes.

Source: https://nodaro.ai/docs/mcp/tools/studio-productions

The **studio production tools** create and change films that open in the Nodaro Studio editor at [studio.nodaro.ai](https://studio.nodaro.ai). This page lists each tool's parameters. [Studio productions](https://nodaro.ai/docs/mcp/studio-productions) explains the loop, the words to use with the user, the edit operations and the spending rules; read it first.

Studio productions are a Nodaro Cloud feature. On a deployment without them, every tool in this family answers `not_available`. Call `list_studio_productions` to check before you offer the feature.

## Tools, permissions and prices

| Tool | Permission | Credits |
| --- | --- | --- |
| `get_studio_production_skill` | none | Free |
| `validate_studio_plan` | `workflows:read` | Free |
| `list_studio_productions` | `workflows:read` | Free |
| `get_studio_production` | `workflows:read` | Free |
| `plan_studio_export` | `workflows:read` | Free, it is a quote |
| `create_studio_production` | `workflows:write` | Free |
| `import_studio_production` | `workflows:write` | Free |
| `edit_studio_production` | `workflows:write` | Free |
| `share_studio_production` | `workflows:write` | Free |
| `clone_studio_production` | `workflows:write` | Free |
| `describe_studio_production` | `workflows:write` and `workflows:execute` | One LLM run |
| `generate_studio_still` | `workflows:write` and `workflows:execute` | Per candidate image |
| `generate_studio_keyframe` | `workflows:write` and `workflows:execute` | One image |
| `generate_studio_clip` | `workflows:write` and `workflows:execute` | One video |
| `new_studio_shot_from_frame` | `workflows:write` and `workflows:execute` | One frame extraction |
| `voice_studio_shot` | `workflows:write` and `workflows:execute` | One text to speech run |
| `revoice_studio_clip` | `workflows:write` and `workflows:execute` | A revoice run |
| `score_studio_production` | `workflows:write` and `workflows:execute` | One music run |

The tools that spend credits, and `share_studio_production`, which changes who can see the work, carry a confirmation mark in their definition. The spending tools accept `client_request_id`, a retry token of 8 to 128 characters: send the same value again after a timeout, and nothing is started or charged twice.

## Plan and read

### `get_studio_production_skill`

Returns the guide an assistant reads before it works on a production. It is generated from the live deployment.

| Parameter | Type | Notes |
| --- | --- | --- |
| `part` | string | `operating` (default): the tool map, the loop and the edit operations. `authoring`: the plan format. `catalog`: every picker, model and option. `schema`: the JSON Schema of a plan. |

### `validate_studio_plan`

Checks an authored plan, free, and saves nothing. It also resolves every `cast` name against your own characters, locations, objects and creatures.

| Parameter | Type | Notes |
| --- | --- | --- |
| `plan` | object | **Required.** The `nodaro-studio-production` plan. |

**Returns:** `valid`, `errors` (each naming its field), `warnings` and a `summary` that says how many cast names matched your library. Fix the errors and call again until `valid` is `true`.

### `list_studio_productions`

Lists your productions, newest first: id, name, version, thumbnail, whether it is shared, and the number of scenes. Archived productions are hidden, as on the dashboard.

| Parameter | Type | Notes |
| --- | --- | --- |
| `limit` | integer | From 1 to 100. Default `25`. |
| `cursor` | string | The `nextCursor` of the previous page. |

### `get_studio_production`

Returns one production: its film look, cast, folders, cuts, bin, what is running, and its scenes in timeline order. With `workflows:write`, it first lands every job that finished since the last read, so this read is how a finished generation reaches its scene.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production id. |
| `detail` | string | `summary` (default): counts and each scene's current frame. `full`: every past result, with the context that made it. |
| `shot_id` | string | Reads one scene only, the cheap read after a generation. |
| `reconcile` | boolean | `false` reads without landing finished jobs. Default `true`. |

**Returns:** the production, and a `pending` block that names what is still running. Address a result by its `key`, the job id or the URL, never by its position.

### `plan_studio_export`

Returns the ordered steps that would export the production, with a credit estimate. It starts nothing and charges nothing: show it to the user before they accept.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production id. |
| `upscale` | boolean | Adds the 4K pass, which is expensive. Default `false`. |

## Create and change

### `create_studio_production`

Creates a production in your own Studio project. It appears on your dashboard at studio.nodaro.ai at once. With a plan, every scene, cast binding and film look lands with it; without one, the production is empty. Validate the plan first.

| Parameter | Type | Notes |
| --- | --- | --- |
| `plan` | object | A validated plan. |
| `name` | string | The name, when the plan has no title of its own. Up to 200 characters. |

### `import_studio_production`

Adds a plan's scenes to an existing production, and enrolls the new cast members. It never renames the production or changes its brief or its look.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `plan` | object | A validated plan. Pass this or `plan_job_id`. |
| `plan_job_id` | string | A finished LLM job whose output is a studio production plan. A job that is still running is refused with `not_finished`. |

**Reload the editor around an import:** 
If the production is open in the studio editor, the editor saves its own copy shortly after any edit and overwrites the scenes you added. Ask the user to reload the editor before the import and again after it.

### `edit_studio_production`

Changes a production with a batch of operations, such as renaming a scene, reordering the timeline, selecting a take, setting the shots inside a scene's motion, enrolling a cast member or emptying the bin. The operations and their arguments are served by `get_studio_production_skill` with `part: "operating"`.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `ops` | array | **Required.** 1 to 100 operations, applied in order. |
| `dry_run` | boolean | Previews the batch: what each operation would do, at which version, and whether each delete could be restored. Nothing is written. |
| `expected_version` | integer | The version you composed the batch against. |
| `strict` | boolean | Refuses with a conflict, instead of rebasing, when the production changed. Needs `expected_version`. |

**Returns:** `receipts`, one past-tense line per operation. The batch is applied as one step: if one operation is refused, the answer names its index and nothing is written. A batch composed against a slightly older version still applies, and `rebased: true` says so.

### `share_studio_production`

Publishes the production to a share link, or makes it private again. Anyone with the link can read a shared production, so ask the user first. This tool is the only way sharing changes.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shared` | boolean | **Required.** `true` publishes the link, `false` takes it back. |

### `clone_studio_production`

Copies a production, yours or one shared with you, into your Studio project. The copy starts private and carries the graph and every landed result. Use it before a risky round of edits.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production to copy. |
| `name` | string | The copy's name. Default: the original name plus " copy". |

## Generate

A generation returns job ids at once. The finished result joins its scene only on the next `get_studio_production`; `get_job` and `wait_for_job` report the status and land nothing.

### `describe_studio_production`

Hands a brief to the Director, which writes scenes, cast and looks into the production. Use it when the user has a story rather than a plan.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `brief` | string | **Required.** The story, the tone and the constraints. |
| `llm_model` | string | **Required.** The LLM that drafts the production, from `list_models`. |
| `mode` | string | `append` (default) adds scenes. `replace` rewrites the production. |
| `label` | string | A name for the run. |
| `client_request_id` | string | A retry token. |

### `generate_studio_still`

Generates candidates for a scene's frame, from what the scene already says: its prompt, references, cast and direction. Generating again adds takes; it never replaces one.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shot_id` | string | **Required.** The scene's id. |
| `count` | integer | How many candidates, from 1 to 10. Default: the scene's own setting. |
| `overrides` | object | Settings for this call only. |
| `dry_run` | boolean | Returns the model and the price, and starts nothing. `credits: null` means the price is unknown, not free. |
| `client_request_id` | string | A retry token. |

### `generate_studio_keyframe`

Generates one candidate for a planned frame, a frame the user reviews and accepts, which is different from a scene's frame. A derived frame needs an accepted parent. There is no quote for this tool, and `dry_run: true` is refused.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `keyframe_id` | string | **Required.** The planned frame. |
| `expected_revision` | integer | **Required.** The revision of the frame plan you reviewed. |
| `overrides` | object | The model, aspect ratio and resolution. The plan owns the prompt and the references. |
| `client_request_id` | string | A retry token. |

Landing the candidate neither accepts it nor starts another frame. Accept it with `edit_studio_production` after review. This tool needs a deployment that supports planned frames.

### `generate_studio_clip`

Generates a scene's motion from its frame, its start and end frames and its direction.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shot_id` | string | **Required.** The scene's id. |
| `mode` | string | Forces a lane: `start` sends only the start frame, `start-end` sends the start and the end frame, and `references` sends the reference media. Leave it out to follow the scene's saved inputs. |
| `overrides` | object | Settings for this call only. |
| `dry_run` | boolean | Returns the model and the price, and starts nothing. |
| `retake_result_key` | string | Retakes an existing linked take with its original settings. Leave `mode` and `overrides` out. |
| `expected_input_hash` | string | Required to submit a retake: the hash from the retake's quote. |
| `client_request_id` | string | A retry token. |

To retake a linked take exactly, first call with `retake_result_key` and `dry_run: true`, and review the price and the `inputHash`. Then submit the same call with `expected_input_hash` and a new `client_request_id`, without `dry_run`. The retake uses the take's original settings and endpoint images, even if the plan changed since. Deployments advertise this with the `operations.retakeLinkedClips` capability.

### `new_studio_shot_from_frame`

Takes a frame from a scene's current motion and puts it to work. The call waits for the extraction and answers with the updated production.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shot_id` | string | **Required.** The scene whose motion you take the frame from. |
| `target` | string | `new-shot` (default) opens the next scene on the frame. `start-frame` or `end-frame` pins it as this scene's endpoint. `still` adds it as a take of this scene's frame. |
| `mode` | string | `first` (default), `last` or `timestamp`. |
| `timestamp` | number | Seconds, for `timestamp`. |
| `client_request_id` | string | A retry token. |

### `voice_studio_shot`

Speaks a line over a scene, as a voiceover. The call waits for the speech and answers with the updated production.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shot_id` | string | **Required.** The scene. |
| `text` | string | **Required.** The line to speak. |
| `voice_id`, `voice_type` | string | A voice from [`list_voices`](https://nodaro.ai/docs/mcp/tools/audio#list_voices). Leave them out to keep the scene's own voice settings. |
| `delivery` | object | Delivery settings, such as speed and stability. |
| `tts_provider` | string | The speech model, when it matters. |
| `client_request_id` | string | A retry token. |

### `revoice_studio_clip`

Replaces the voices inside a scene's current motion: the dialogue is performed again and mixed back over the same picture.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `shot_id` | string | **Required.** The scene. |
| `plan` | object | **Required.** Which speaker gets which voice. The operating guide describes its shape. |
| `client_request_id` | string | A retry token. |

### `score_studio_production`

Writes one soundtrack for the whole production from a description of the music.

| Parameter | Type | Notes |
| --- | --- | --- |
| `production_id` | string | **Required.** The production. |
| `prompt` | string | **Required.** The music: mood, instruments, genre. Up to 2,000 characters. |
| `duration` | number | Seconds, from 1 to 600. |
| `instrumental` | boolean | No vocals. |
| `vocal_gender` | string | The singer's voice. |
| `model` | string | The music model, from `list_models`. |
| `client_request_id` | string | A retry token. |

## Frequently asked questions

### Which studio tools cost credits?

describe_studio_production, generate_studio_still, generate_studio_keyframe, generate_studio_clip, new_studio_shot_from_frame, voice_studio_shot, revoice_studio_clip and score_studio_production. Reading, validating, creating, editing, sharing and cloning a production are free.

### Why do the studio generation tools not appear in my assistant?

They need both workflows:write and workflows:execute. A connection that granted only one of the two sees none of them. Reconnect and allow both permissions.

### Why is a finished frame not in my production yet?

A finished job reaches its scene only when get_studio_production reads the production with write permission. get_job and wait_for_job report the status but land nothing. Read the production again.

### How do I see the price before generating?

Pass dry_run true to generate_studio_still or generate_studio_clip. The tool returns the model and the credits and starts nothing. plan_studio_export quotes the export.