# Produções do Studio

> Parâmetros de cada ferramenta de produção do Studio, da validação grátis do plano à geração de quadros, movimento, voz e trilha, com escopos e cotações.

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

As **ferramentas de produção do Studio** criam e alteram filmes que abrem no editor do Nodaro Studio, em [studio.nodaro.ai](https://studio.nodaro.ai). Esta página lista os parâmetros de cada ferramenta. [Produções do Studio](https://nodaro.ai/docs/mcp/studio-productions) explica o ciclo de trabalho, as palavras a usar com o usuário, as operações de edição e as regras de gasto; leia essa página primeiro.

As produções do Studio são um recurso do Nodaro Cloud. Numa implantação sem elas, todas as ferramentas desta família respondem `not_available`. Chame `list_studio_productions` para verificar antes de oferecer o recurso.

## Ferramentas, permissões e preços
| Ferramenta | Permissão | Créditos |
| --- | --- | --- |
| `get_studio_production_skill` | nenhuma | Grátis |
| `validate_studio_plan` | `workflows:read` | Grátis |
| `list_studio_productions` | `workflows:read` | Grátis |
| `get_studio_production` | `workflows:read` | Grátis |
| `plan_studio_export` | `workflows:read` | Grátis; é uma cotação |
| `create_studio_production` | `workflows:write` | Grátis |
| `import_studio_production` | `workflows:write` | Grátis |
| `edit_studio_production` | `workflows:write` | Grátis |
| `share_studio_production` | `workflows:write` | Grátis |
| `clone_studio_production` | `workflows:write` | Grátis |
| `describe_studio_production` | `workflows:write` e `workflows:execute` | Uma execução de LLM |
| `generate_studio_still` | `workflows:write` e `workflows:execute` | Por imagem candidata |
| `generate_studio_keyframe` | `workflows:write` e `workflows:execute` | Uma imagem |
| `generate_studio_clip` | `workflows:write` e `workflows:execute` | Um vídeo |
| `new_studio_shot_from_frame` | `workflows:write` e `workflows:execute` | Uma extração de quadro |
| `voice_studio_shot` | `workflows:write` e `workflows:execute` | Uma execução de texto para fala |
| `revoice_studio_clip` | `workflows:write` e `workflows:execute` | Uma execução de redublagem |
| `score_studio_production` | `workflows:write` e `workflows:execute` | Uma execução de música |

As ferramentas que gastam créditos, e `share_studio_production`, que muda quem pode ver o trabalho, trazem uma marca de confirmação na definição. As ferramentas que gastam créditos aceitam `client_request_id`, um token de nova tentativa de 8 a 128 caracteres: envie o mesmo valor de novo depois de uma chamada que expirou, e nada é iniciado nem cobrado duas vezes.

## Planejar e ler
### `get_studio_production_skill`
Retorna o guia que um assistente lê antes de trabalhar numa produção. Ele é gerado a partir da implantação ativa.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `part` | string | `operating` (padrão): o mapa das ferramentas, o ciclo de trabalho e as operações de edição. `authoring`: o formato do plano. `catalog`: todos os seletores, modelos e opções. `schema`: o JSON Schema de um plano. |

### `validate_studio_plan`
Verifica um plano escrito, de graça, e não salva nada. Também associa cada nome de `cast` aos seus próprios personagens, locais, objetos e criaturas.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `plan` | object | **Obrigatório.** O plano `nodaro-studio-production`. |

**Retorna:** `valid`, `errors` (cada um indicando o campo dele), `warnings` e um `summary` que diz quantos nomes do elenco corresponderam à sua biblioteca. Corrija os erros e chame de novo até `valid` ser `true`.

### `list_studio_productions`
Lista as suas produções, das mais recentes para as mais antigas: ID, nome, versão, miniatura, se ela está compartilhada e o número de cenas. As produções arquivadas ficam ocultas, como no painel.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `limit` | integer | De 1 a 100. Padrão: `25`. |
| `cursor` | string | O `nextCursor` da página anterior. |

### `get_studio_production`
Retorna uma produção: o look do filme, o elenco, as pastas, os cortes, a lixeira, o que está em execução e as cenas na ordem da linha do tempo. Com `workflows:write`, ela primeiro incorpora cada job que terminou desde a última leitura; é por essa leitura que uma geração concluída chega à cena dela.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** O ID da produção. |
| `detail` | string | `summary` (padrão): contagens e o quadro atual de cada cena. `full`: cada resultado anterior, com o contexto que o gerou. |
| `shot_id` | string | Lê só uma cena: a leitura barata depois de uma geração. |
| `reconcile` | boolean | `false` lê sem incorporar os jobs concluídos. Padrão: `true`. |

**Retorna:** a produção e um bloco `pending` que indica o que ainda está em execução. Identifique um resultado pela `key`, pelo ID do job ou pela URL, nunca pela posição.

### `plan_studio_export`
Retorna as etapas ordenadas que exportariam a produção, com uma estimativa de créditos. Não inicia nem cobra nada: mostre-a ao usuário antes que ele aceite.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** O ID da produção. |
| `upscale` | boolean | Adiciona a passagem em 4K, que é cara. Padrão: `false`. |

## Criar e alterar
### `create_studio_production`
Cria uma produção no seu próprio projeto do Studio. Ela aparece na hora no seu painel em studio.nodaro.ai. Com um plano, todas as cenas, os vínculos do elenco e o look do filme entram junto; sem plano, a produção fica vazia. Valide o plano primeiro.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `plan` | object | Um plano validado. |
| `name` | string | O nome, quando o plano não tem título próprio. Até 200 caracteres. |

### `import_studio_production`
Adiciona as cenas de um plano a uma produção existente e inclui os novos membros no elenco. Nunca renomeia a produção nem altera o briefing ou o look dela.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `plan` | object | Um plano validado. Passe este parâmetro ou `plan_job_id`. |
| `plan_job_id` | string | Um job de LLM concluído cuja saída é um plano de produção do Studio. Um job ainda em execução é recusado com `not_finished`. |

**Recarregue o editor antes e depois de uma importação:** 
Se a produção estiver aberta no editor do Studio, o editor salva a própria cópia logo após qualquer edição e sobrescreve as cenas que você adicionou. Peça ao usuário para recarregar o editor antes da importação e de novo depois dela.

### `edit_studio_production`
Altera uma produção com um lote de operações, como renomear uma cena, reordenar a linha do tempo, selecionar um take, definir as tomadas dentro do movimento de uma cena, incluir um membro no elenco ou esvaziar a lixeira. As operações e os argumentos delas vêm de `get_studio_production_skill` com `part: "operating"`.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `ops` | array | **Obrigatório.** De 1 a 100 operações, aplicadas em ordem. |
| `dry_run` | boolean | Mostra uma prévia do lote: o que cada operação faria, em qual versão e se cada exclusão poderia ser restaurada. Nada é gravado. |
| `expected_version` | integer | A versão sobre a qual você montou o lote. |
| `strict` | boolean | Recusa com um conflito, em vez de fazer rebase, quando a produção mudou. Exige `expected_version`. |

**Retorna:** `receipts`, uma linha no passado por operação. O lote é aplicado como uma única etapa: se uma operação for recusada, a resposta indica o índice dela e nada é gravado. Um lote montado sobre uma versão um pouco mais antiga ainda é aplicado, e `rebased: true` indica isso.

### `share_studio_production`
Publica a produção num link de compartilhamento ou a torna privada de novo. Qualquer pessoa com o link pode ler uma produção compartilhada, então pergunte ao usuário antes. Esta ferramenta é a única forma de mudar o compartilhamento.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shared` | boolean | **Obrigatório.** `true` publica o link, `false` o retira. |

### `clone_studio_production`
Copia uma produção, sua ou compartilhada com você, para o seu projeto do Studio. A cópia começa privada e traz o grafo e todos os resultados já incorporados. Use-a antes de uma rodada de edições arriscada.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção a copiar. |
| `name` | string | O nome da cópia. Padrão: o nome original mais “ copy”. |

## Gerar
Uma geração retorna IDs de job na hora. O resultado pronto só entra na cena dele na próxima chamada de `get_studio_production`; `get_job` e `wait_for_job` informam o status e não incorporam nada.

### `describe_studio_production`
Entrega um briefing ao Diretor, que escreve cenas, elenco e looks na produção. Use-a quando o usuário tiver uma história em vez de um plano.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `brief` | string | **Obrigatório.** A história, o tom e as restrições. |
| `llm_model` | string | **Obrigatório.** O LLM que esboça a produção, de `list_models`. |
| `mode` | string | `append` (padrão) adiciona cenas. `replace` reescreve a produção. |
| `label` | string | Um nome para a execução. |
| `client_request_id` | string | Um token de nova tentativa. |

### `generate_studio_still`
Gera candidatas para o quadro de uma cena, a partir do que a cena já diz: o prompt, as referências, o elenco e a direção. Gerar de novo adiciona takes; nunca substitui um take.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shot_id` | string | **Obrigatório.** O ID da cena. |
| `count` | integer | Quantas candidatas, de 1 a 10. Padrão: a configuração da própria cena. |
| `overrides` | object | Configurações só para esta chamada. |
| `dry_run` | boolean | Retorna o modelo e o preço e não inicia nada. `credits: null` significa que o preço é desconhecido, não que é grátis. |
| `client_request_id` | string | Um token de nova tentativa. |

### `generate_studio_keyframe`
Gera uma candidata para um quadro planejado: um quadro que o usuário revisa e aceita, diferente do quadro de uma cena. Um quadro derivado precisa de um quadro de origem aceito. Não há cotação para esta ferramenta, e `dry_run: true` é recusado.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `keyframe_id` | string | **Obrigatório.** O quadro planejado. |
| `expected_revision` | integer | **Obrigatório.** A revisão do plano de quadros que você revisou. |
| `overrides` | object | O modelo, a proporção e a resolução. O plano controla o prompt e as referências. |
| `client_request_id` | string | Um token de nova tentativa. |

Incorporar a candidata não a aceita nem inicia outro quadro. Aceite-a com `edit_studio_production` depois da revisão. Esta ferramenta precisa de uma implantação compatível com quadros planejados.

### `generate_studio_clip`
Gera o movimento de uma cena a partir do quadro dela, dos quadros inicial e final e da direção.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shot_id` | string | **Obrigatório.** O ID da cena. |
| `mode` | string | Força um caminho: `start` envia só o quadro inicial, `start-end` envia os quadros inicial e final, e `references` envia as mídias de referência. Omita-o para seguir as entradas salvas da cena. |
| `overrides` | object | Configurações só para esta chamada. |
| `dry_run` | boolean | Retorna o modelo e o preço e não inicia nada. |
| `retake_result_key` | string | Refaz um take vinculado existente com as configurações originais dele. Omita `mode` e `overrides`. |
| `expected_input_hash` | string | Obrigatório para enviar um retake: o hash da cotação desse retake. |
| `client_request_id` | string | Um token de nova tentativa. |

Para refazer um take vinculado exatamente igual, chame primeiro com `retake_result_key` e `dry_run: true` e confira o preço e o `inputHash`. Depois, envie a mesma chamada com `expected_input_hash` e um novo `client_request_id`, sem `dry_run`. O retake usa as configurações originais e as imagens inicial e final do take, mesmo que o plano tenha mudado desde então. As implantações anunciam esse recurso com a capacidade `operations.retakeLinkedClips`.

### `new_studio_shot_from_frame`
Pega um quadro do movimento atual de uma cena e o reaproveita. A chamada aguarda a extração e responde com a produção atualizada.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shot_id` | string | **Obrigatório.** A cena de cujo movimento você tira o quadro. |
| `target` | string | `new-shot` (padrão) abre a próxima cena com esse quadro. `start-frame` ou `end-frame` o fixa como quadro inicial ou final desta cena. `still` o adiciona como um take do quadro desta cena. |
| `mode` | string | `first` (padrão), `last` ou `timestamp`. |
| `timestamp` | number | Segundos, para `timestamp`. |
| `client_request_id` | string | Um token de nova tentativa. |

### `voice_studio_shot`
Fala uma frase sobre uma cena, como narração. A chamada aguarda a fala e responde com a produção atualizada.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shot_id` | string | **Obrigatório.** A cena. |
| `text` | string | **Obrigatório.** A frase a falar. |
| `voice_id`, `voice_type` | string | Uma voz de [`list_voices`](https://nodaro.ai/docs/mcp/tools/audio#list_voices). Omita-os para manter as configurações de voz da própria cena. |
| `delivery` | object | Configurações de locução, como velocidade e estabilidade. |
| `tts_provider` | string | O modelo de fala, quando isso importa. |
| `client_request_id` | string | Um token de nova tentativa. |

### `revoice_studio_clip`
Substitui as vozes dentro do movimento atual de uma cena: o diálogo é interpretado de novo e mixado de volta sobre a mesma imagem.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `shot_id` | string | **Obrigatório.** A cena. |
| `plan` | object | **Obrigatório.** Qual falante recebe qual voz. O guia de operação descreve o formato. |
| `client_request_id` | string | Um token de nova tentativa. |

### `score_studio_production`
Compõe uma trilha sonora para a produção inteira a partir de uma descrição da música.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `production_id` | string | **Obrigatório.** A produção. |
| `prompt` | string | **Obrigatório.** A música: clima, instrumentos, gênero. Até 2.000 caracteres. |
| `duration` | number | Segundos, de 1 a 600. |
| `instrumental` | boolean | Sem vocais. |
| `vocal_gender` | string | A voz do cantor. |
| `model` | string | O modelo de música, de `list_models`. |
| `client_request_id` | string | Um token de nova tentativa. |

## Frequently asked questions

### Quais ferramentas do Studio custam créditos?

describe_studio_production, generate_studio_still, generate_studio_keyframe, generate_studio_clip, new_studio_shot_from_frame, voice_studio_shot, revoice_studio_clip e score_studio_production. Ler, validar, criar, editar, compartilhar e clonar uma produção é grátis.

### Por que as ferramentas de geração do Studio não aparecem no meu assistente?

Elas precisam de workflows:write e workflows:execute juntas. Uma conexão que concedeu só uma das duas não vê nenhuma delas. Conecte-se de novo e conceda as duas permissões.

### Por que um quadro pronto ainda não está na minha produção?

Um job concluído só chega à cena dele quando get_studio_production lê a produção com permissão de escrita. get_job e wait_for_job informam o status, mas não incorporam nada. Leia a produção de novo.

### Como vejo o preço antes de gerar?

Passe dry_run true para generate_studio_still ou generate_studio_clip. A ferramenta retorna o modelo e os créditos e não inicia nada. plan_studio_export faz a cotação da exportação.