# Produções do Studio

> Dirija um filme com um assistente de IA como produção do Studio, valide o plano de graça, gere quadros e movimento com cotação e siga editando no Studio.

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

Uma **produção do Studio** é um filme que um assistente de IA pode dirigir a partir de uma conversa e que você continua editando no editor do Studio, em [studio.nodaro.ai](https://studio.nodaro.ai). Ela é uma lista ordenada de cenas, cada uma com um quadro, um movimento opcional e o plano, os visuais, o elenco e a voz que os criaram. Um assistente pode fazer o rascunho do filme, entregá-lo a você e retomá-lo depois que você mudou três cenas de lugar. As produções do Studio são um recurso do Nodaro Cloud.

Escolha este caminho para pedidos como “faça um filme, uma cena ou uma sequência e me deixe continuar editando”. Para um filme escrito como um único documento JSON, veja [Recast](https://nodaro.ai/docs/mcp/recast); para um workflow no canvas, veja o [Film Director](https://nodaro.ai/docs/mcp/film-director).

## Dois vocabulários
O editor e o documento da produção dão nomes diferentes às mesmas coisas. A pessoa só vê o editor; por isso, o assistente usa as palavras do editor e reserva os nomes do documento para as chamadas de ferramentas.

| O usuário diz | O documento diz |
| --- | --- |
| **filme** | a produção |
| **cena**, como “Cena 3”, um cartão na linha do tempo | uma entrada de `shots[]`, endereçada por `shot_id` |
| o **quadro** de uma cena, cujos resultados são takes | `still` |
| o **movimento** de uma cena, cujos resultados são takes | `clip` |
| as **tomadas** dentro de um movimento | `beats[]`, definidas com `set_beats` |

- **“Cena N” é sempre a N-ésima entrada de `shots[]`.** “Renomeie a cena 3” é `rename_shot` nessa entrada, e “exclua a cena 3” é `remove_shot` nela.
- **“Tomada” significa uma tomada dentro de um movimento**, uma entrada de `beats[]` da cena que o usuário está vendo, nunca uma entrada de `shots[]`. Quando nenhuma cena está à vista, ou o movimento dela tem menos tomadas do que o usuário mencionou, o assistente pergunta em vez de adivinhar.
- **O quadro de uma cena é o `still` dela.** Um quadro planejado é outra coisa: um plano de quadro que o usuário revisa e aceita, feito com `generate_studio_keyframe`. O quadro inicial e o quadro final de uma cena são as extremidades do movimento dela.
- **Os recibos usam as palavras do documento.** Os nomes das operações e os `receipts` de uma edição dizem “shot” quando querem dizer cena; o assistente não deve repetir esse termo para o usuário.

## O ciclo
### Ler o guia
`get_studio_production_skill` retorna o guia em quatro partes: `operating` (as ferramentas, o ciclo e as operações), `authoring` (o formato do plano), `catalog` (todos os seletores, modelos e opções) e `schema` (o JSON Schema do plano). Ele é gerado a partir da implantação ativa; por isso, corresponde ao servidor que você usa. Gratuito.

### Validar o plano
`validate_studio_plan` verifica um plano de graça, não salva nada e compara os nomes do elenco com a sua própria biblioteca. Corrija cada `errors[].path` até o plano ficar válido, antes de qualquer gasto.

### Criar a produção
`create_studio_production` cria um novo filme, com as cenas do plano, se você passar um. `import_studio_production` adiciona as cenas de um plano a um filme existente. As duas são gratuitas. Para uma história sem plano, `describe_studio_production` pede ao Diretor que escreva as cenas, em uma execução de LLM.

### Ler a produção de novo
`get_studio_production` retorna o filme como está, mais um bloco `pending` com o que ainda está em andamento. Com permissão de escrita, a leitura primeiro incorpora tudo o que terminou; por isso, é ao ler de novo que uma geração concluída chega à cena dela. Passe `shot_id` para uma leitura leve de uma única cena.

### Editar com operações
`edit_studio_production` aplica um lote de operações. Veja [Edição com operações](#editing-with-operations).

### Gerar
`generate_studio_still` faz o quadro de uma cena, `generate_studio_clip` faz o movimento dela, `new_studio_shot_from_frame` tira um quadro de um movimento, `voice_studio_shot` dá voz a uma fala, `revoice_studio_clip` troca as vozes de um movimento e `score_studio_production` compõe a trilha sonora.

### Exportar e compartilhar
`plan_studio_export` lista as etapas que montam o filme, cada uma com o preço dela. `share_studio_production` abre ou fecha um link de compartilhamento, e `clone_studio_production` faz uma cópia.

Uma conversa abandonada não deixa nada pela metade. A produção é um filme real que você pode abrir no editor, e uma geração que ainda estava em andamento é incorporada na próxima vez que a produção for atualizada, por você, pelo editor ou pelo próximo assistente.

## Edição com operações
Toda mudança em uma produção é uma **operação**, e `edit_studio_production` é a única ferramenta que as aplica. Um lote é aplicado em um único passo sobre a versão mais recente do documento.

- **As operações identificam as coisas por chaves estáveis**: uma cena pelo ID, um membro do elenco pelo slug do papel, um resultado pelo ID do job ou pela URL. Nunca pela posição, porque o usuário pode estar editando o mesmo filme no navegador.
- **Um lote montado sobre uma versão um pouco mais antiga ainda é aplicado**, e a resposta informa que houve um rebase. Com `strict: true` e `expected_version`, o lote é recusado.
- **Uma operação inválida faz o lote inteiro ser recusado**, e nada é gravado. O erro indica a operação pelo índice dela, contado a partir de 0; corrija-a e envie o lote de novo.
- **`receipts` tem uma linha no passado por operação**, e é isso que deve ser mostrado a um usuário que pergunta o que acabou de acontecer.
- **Algumas exclusões podem ser desfeitas.** Uma cena, um take ou um quadro planejado removido vai para a lixeira da produção e pode ser restaurado. Limpar um membro do elenco, uma voz ou a trilha sonora, excluir um corte, remover uma sequência, apagar de vez um item da lixeira e esvaziar a lixeira não podem ser desfeitos.
- **Compartilhar não é uma operação.** O compartilhamento tem a própria ferramenta; assim, um lote de edição nunca pode mudar quem pode ver o trabalho.
- **Não é possível excluir uma produção.** Arquivá-la é uma operação, e pode ser desfeita.

O vocabulário das operações é fornecido pelo servidor, não reproduzido aqui: `get_studio_production_skill` com `part: "operating"` retorna o que a implantação aceita.

### Pré-visualizar um lote
`edit_studio_production` com `dry_run: true` responde o que o lote faria e não grava nada. O recibo de cada operação traz uma classe: `S` altera o documento, `D` exclui, `P` muda quem pode acessar o trabalho e `$` gera gasto. Uma exclusão que iria para a lixeira é marcada com `restorable: true`. Mostre a prévia ao usuário e depois envie o mesmo lote sem `dry_run`.

A ferramenta verifica antes se a implantação aceita prévias e, se não aceitar, recusa com `studio_preview_unavailable`, sem ter enviado nada. Os IDs de uma prévia não são os IDs da mudança real: para desfazer, leia os IDs da lixeira nos recibos do lote aplicado.

## Gastos
Um assistente que dirige um filme faz dezenas de chamadas; por isso, dois hábitos importam.

- **Peça a cotação primeiro.** `generate_studio_still` e `generate_studio_clip` aceitam `dry_run: true`, que retorna o modelo e o preço e não grava nada. `credits: null` significa que o preço é desconhecido, não que é gratuito. Mostre o preço e deixe o usuário aceitar. As outras ferramentas que geram gasto não têm cotação: calcule o preço pelo modelo ou pergunte antes.
- **Repita com segurança.** Todas as ferramentas que geram gasto aceitam `client_request_id`, de 8 a 128 caracteres de `A-Za-z0-9_.:-`. O mesmo token responde com os jobs da primeira chamada e não cobra nada de novo. Crie um token novo para cada novo pedido e nunca repita uma chamada que gera gasto sem um token.

A geração segue a ordem **executar, consultar e incorporar**:

1. Uma chamada de quadro ou de movimento retorna os IDs dos jobs na hora.
2. Espere esses jobs com `get_job` ou acompanhe o bloco `pending` da produção.
3. Leia a produção de novo com `get_studio_production`. Com permissão de escrita, a leitura incorpora todos os jobs concluídos antes de responder.
4. Mostre ao usuário o que chegou.

Com permissão só de leitura, a leitura não incorpora nada, e um job concluído continua em `pending` até que alguém com permissão de escrita atualize a produção.

## Marcas de confirmação
Uma ferramenta que gasta créditos, ou que muda quem pode ver o trabalho, informa isso na própria definição, em `_meta.nodaro.confirm`. Um cliente pode exibir um pedido de confirmação antes de toda ferramenta com essa marca, em vez de manter a própria lista.

| Marca | Por que perguntar antes | Ferramentas |
| --- | --- | --- |
| `$` | Custa 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`, `score_studio_production` |
| `P` | Muda quem pode ver o trabalho. | `share_studio_production` |

`edit_studio_production` não tem marca: o que um lote faz depende das operações dele. Para confirmar antes de uma exclusão, pré-visualize o lote, em que cada operação vem classificada.

## Permissões
As oito ferramentas que geram gasto precisam de `workflows:write` e de `workflows:execute`. Uma conexão que concedeu só uma das duas não vê nenhuma delas, sem explicação; por isso, conceda as duas para gerar. Ler precisa de `workflows:read`, e criar, editar, compartilhar e clonar precisam de `workflows:write`. A [referência de ferramentas](https://nodaro.ai/docs/mcp/tools/studio-productions) lista a permissão e os parâmetros de cada ferramenta.

## Disponibilidade
Em uma implantação que não oferece produções do Studio, todas as ferramentas da família respondem `not_available`, uma recusa simples que não vale a pena repetir. Chame `list_studio_productions` para verificar antes de oferecer o recurso.

## Onde o formato do plano está documentado
O formato do plano, `nodaro-studio-production`, tem um único lugar publicado. O app do Studio serve o mesmo guia de criação, o mesmo catálogo e o mesmo JSON Schema em [studio.nodaro.ai/skills/studio-production/](https://studio.nodaro.ai/skills/studio-production/). Assim, um assistente que lê `get_studio_production_skill` e uma pessoa que lê essa página leem o mesmo documento.

O mesmo caminho de produção está disponível pela API REST, em [Produções do Studio](https://nodaro.ai/docs/developers/api/studio-productions), e no SDK como `client.studio.productions`.

## Frequently asked questions

### O que é uma produção do Studio?

Um filme feito de cenas, cada uma com um quadro, um movimento opcional e o plano, os visuais, o elenco e a voz que os criaram. Ele abre no editor do Studio, em studio.nodaro.ai; assim, um assistente pode fazer o rascunho e você pode continuar editando à mão.

### Por que o assistente chama uma cena de “shot” em alguns lugares?

As chaves do documento da produção chamam uma cena de “shot”. Na conversa, o assistente deve sempre usar as suas palavras (cena, quadro, movimento e tomada) e reservar os nomes do documento para as chamadas de ferramentas.

### Quando uma geração concluída aparece no filme?

Quando a produção é lida de novo com get_studio_production por uma sessão com permissão de escrita. Essa leitura incorpora todos os jobs que terminaram desde a leitura anterior. get_job e wait_for_job só informam o status.

### Uma edição pode ser desfeita?

Muitas exclusões podem. Uma cena, um take ou um quadro planejado removido vai para a lixeira da produção e pode ser restaurado. Limpar um membro do elenco, uma voz ou a trilha sonora, excluir um corte ou esvaziar a lixeira não pode ser desfeito. Uma prévia informa quais exclusões são restauráveis.

### Qual é a diferença em relação ao Film Director?

O Film Director monta um workflow no canvas. Uma produção do Studio é um filme que você continua editando cena a cena no editor do Studio, o que combina com pedidos como “faça um filme para mim e me deixe continuar editando”.