Produções do Studio

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. 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; para um workflow no canvas, veja o 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.

• “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

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.

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 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/. 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, e no SDK como client.studio.productions.