5.0 Trabalhe com o seu próprio Claude5.2 O que o Claude faz
O que o Claude faz
Toda ferramenta MCP que o Filmsquare dá ao seu Claude, como find_actions e run_action chegam ao resto da API, e o que fica de fora de propósito.
O seu Claude pode fazer no Filmsquare o que a API deixa a sua função fazer. Dezoito ferramentas nomeadas cobrem o trabalho do dia a dia;
mais duas, find_actions e run_action, chegam a toda outra ação da API. Toda chamada passa pela própria API, como
você: as mesmas checagens de função, a mesma validação, as mesmas liberações.
As ferramentas nomeadas #
| Ferramenta | O que faz | Precisa de |
|---|---|---|
whats_waiting | Etapas de departamento aguardando a sua aprovação, e as suas notificações não lidas. O lugar de começar | — |
list_productions | As produções do espaço de trabalho com os seus episódios | — |
get_episode | Um episódio: cenas e planos na ordem do corte, cada etapa de departamento (aprovada, aguardando quem, ajustes pedidos, aberta), e se os finais podem ser renderizados | episode_id |
get_feedback | Conversas de comentários em um plano, take, episódio, cena, elemento, pasta, versão de material, canvas ou caixa de canvas, com cada mensagem e a sua marcação (timecode em frames, ou uma região da imagem). Conversas abertas por padrão; status resolved ou all para o resto. Com target_type sheet: as notas abertas na última versão da ficha (intenção, citação ou a ficha inteira, texto sugerido, tratada ou não) e como terminaram as notas das versões anteriores | target_type, target_id |
reply_feedback | Responde em uma conversa como você (menções @nome notificam pessoas), e a resolve quando a nota foi tratada. Uma nota em uma ficha é marcada como tratada; quando tem uma sugestão, suggestion_outcome (aplicada, adaptada ou recusada) é obrigatório, e uma pessoa a confirma | thread_id, body |
view_media | Um still, keyframe ou take como uma imagem que o Claude pode olhar; um vídeo volta como o seu pôster mais um link de download | asset_version_id |
upload_file | Um arquivo da conversa para uma camada de plano ou de cena como novo take, ou para uma produção como material. No máximo 10 MB. pick: true também o escolhe (diretor(a) e acima) | name, mime, data_base64 |
where_does_it_go | Em qual tela um arquivo deve ficar: o mapa, uma árvore de decisão e exemplos prontos. Leia quando você citar uma tela | — |
prepare_upload | URLs de envio assinadas e comandos curl prontos para até 100 arquivos do disco, para os bytes nunca passarem pela conversa. Use para todo vídeo | files |
add_to_visualize | Põe arquivos enviados em Storyboard → 3D ou Storyboard → Animatic, até 100 por chamada, em planos e cenas pelo código. Enviar o mesmo de novo não muda nada | episode_id, items |
get_script | O último tratamento do roteiro do episódio, e os @handles do elenco, cenários e objetos de cena que já existem | episode_id |
edit_script | Altera uma cena, uma fala ou uma linha do roteiro sem enviar tudo: o texto exato e o que o substitui, salvo como uma nova versão; notas e marcações vão junto | episode_id, base_rev, edits |
submit_breakdown | Põe a decupagem do Claude no Filmsquare: cenas, planos com atuação, diálogo, elenco, cenários e objetos de cena. O Roteiro então aguarda aprovação | episode_id, breakdown |
get_continuity | A ficha de continuidade de um episódio: o que cada plano toca, os elementos e as suas referências, com o que cada take escolhido foi feito, achados até agora, planos a checar de novo. Roda antes a checagem de linhagem gratuita | episode_id |
report_continuity | Registra uma checagem visual de continuidade; cada divergência vira uma nota no take escolhido | episode_id, seen, issues |
submit_style | Coloca um guia de estilo na biblioteca de estilos (Create → Styles): um estilo novo ou, com style_id, a próxima versão dele; production_id o torna de uma produção. O trabalho próprio leva até 6 stills de referência (enviados com prepare_upload); o trabalho de outra pessoa fica só em texto e nunca é publicado. Nomes de pessoas ou de marcas são recusados. Função de artista | name, guide |
request_signoff | Pede aos aprovadores de um departamento que aprovem a etapa de um episódio; eles recebem uma notificação | episode_id, department |
sign_off | Registra a sua decisão sobre uma etapa: approved ou changes_requested, com uma note opcional. Só os aprovadores da etapa podem. Com expect_version (a versão da etapa como você a viu), é recusado com changed_since quando o trabalho se mexeu. Só quando você pediu ao Claude que decidisse | episode_id, department, decision |
studio_analytics | Para o proprietário e os produtores: como o estúdio está indo, com os números de Analytics. view crew (por pessoa em um período: entregues, créditos por entregue, tempo até a aprovação, primeira passada, lanes, refação, horas de mão na massa e do agente sozinho, a mediana do estúdio e o tempo por etapa), day, costs, ou report (o texto do e-mail do relatório como seria enviado). Qualquer outra pessoa é recusada: vê só os próprios números | view |
Toda ferramenta também aceita um workspace opcional. Deixe de fora: o espaço de trabalho da conexão é usado.
department é um de writing, breakdown, casting, voice, wardrobe, sets, props, animatic,
music, draft, sound, edit, final.
Para onde vai a mídia #
Diga ao seu Claude a tela com as suas próprias palavras ("coloque em 3D"). Isto é o que ele faz:
| Você tem | Vai para | Com |
|---|---|---|
| Render clay ou still de um plano, com lente, altura e movimento | Storyboard → 3D, no plano | add_to_visualize |
| Clipe do Blender de um plano, um take ou uma cena | Storyboard → 3D, no que ele cobre | add_to_visualize |
| Animatic de uma cena, sequência ou episódio | Storyboard → Animatic | add_to_visualize |
| Vídeo de prévia ou final de um plano | Storyboard → Shots, como um take | upload_file |
| Imagem de referência ou mood board | Home → Files | upload_file |
Algo no lugar errado muda de lugar sem enviar de novo: moveTake ou moveAsset por run_action (diretor(a) e acima). Uma escolha que a importação fez é limpa com a mudança. Um take que alguém escolheu, ou que foi gerado aqui, fica onde está.
find_actions e run_action #
Tudo o que não tem ferramenta nomeada passa por estas duas: criar planos, escolher takes, fazer prévias, estimativas, elementos e versões, pastas, canvases, custos, briefings, equipe.
find_actionsbusca no catálogo da própria API com poucas palavras, como "pick take", "create shot" ou "resolve thread". Devolve as ações que combinam com o método, o caminho, um resumo, a função mínima e as entradas.run_actionexecuta uma pelo nome, compath_params(não o espaço de trabalho),queryebodycomo a ação descreve. Responde com o JSON da API.
find_actions entende linguagem de set. Ele mapeia as palavras que uma equipe usa para as palavras da API:
| Você diz | Ele também busca |
|---|---|
| pick, choose | select |
| note, notes, comment, comments, feedback | thread, message |
| reply | message |
| render | generation, generate |
| make | create, generate |
| new, add | create |
| remove, delete | archive |
| sign | signoff |
| approve | signoff, approval |
| cast, character, prop | element |
| set | element, location |
| production, productions | project |
| crew | member, steps |
| cost | costs, estimate |
| price | estimate |
| prompt, preview, dry run | generate |
| kosten, schatting, prijs (neerlandês) | generate, estimate |
| mismatch | continuity |
| model, models | models, acceptance, routing |
As ações novas da API aparecem em find_actions no momento em que saem. Nenhuma ferramenta nova é necessária.
Exemplos #
| Para | Busca | Ação |
|---|---|---|
| Dar o preço de uma prévia antes de renderizar | "estimate shot" | estimateShotGeneration |
| Ver o prompt, o modelo e os créditos antes de renderizar | "dry run" | generateForShot com {"kind": "video", "tier": "draft", "dryRun": true} |
| Renderizar uma prévia | "generate shot" | generateForShot com {"kind": "video", "tier": "draft"} |
| Escolher um take | "pick take" | selectTake |
| Tornar uma prévia final | "promote" | promoteGeneration |
| Novo take a partir de uma nota | "revise take" | estimateReviseTake, depois reviseTake |
| Ver qual modelo é aprovado | "model acceptance" | getModelAcceptance |
| Custo de um episódio | "episode costs" | getEpisodeCosts |
Antes de renderizar, o Claude chama a ação de gerar com dryRun: true: ela mostra o prompt compilado, o modelo, as
referências e os créditos, e não faz nada. Ele pode então mudar o prompt para aquela renderização.
overrides.prompt substitui o texto do prompt (as linhas de referência ficam, então elenco, cenários e objetos de cena sempre vão junto),
overrides.promptAppend acrescenta a ele, e overrides.negativePrompt acrescenta o que evitar. O diálogo é falado a partir das suas
linhas e não aceita substituição de prompt.
O dry run responde com provider e model_key. Devolvê-los como provider e modelKey fixa aquele modelo.
getGeneration lê de volta com o que um take foi feito: o prompt, o modelo, os créditos estimados e os créditos
lançados.
Quando a API recusa #
Uma recusa volta como erro de ferramenta com o código e os detalhes da API, por exemplo
The API refused: 409 gate_closed: finals render once casting, sets, animatic are signed off {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}.
O Claude lê e diz a você o que falta. Veja Erros que você vai encontrar.
O que fica de fora de propósito #
O Claude não alcança estes, de propósito:
- Chaves de API e conexões do Claude: uma conexão nunca cria chaves nem permite outras conexões. Uma pessoa faz isso, conectada.
- OAuth e cadastro.
- Webhooks: eles mandam dados para fora do Filmsquare.
- Callbacks de provedores e os sockets em tempo real (canvas e presença).
A liberação dos finais, as checagens de créditos e os limites da assinatura valem para o Claude exatamente como para qualquer pessoa.
Segurança #
- O Claude age como você. Ele tem a sua função (ou a mais baixa que você escolheu ao conectar), e o que faz aparece em seu nome.
- O material da equipe não são instruções. Comentários, roteiros e outros textos que o Claude lê no Filmsquare são material da equipe. O Filmsquare avisa o Claude disso: só você decide o que ele faz.
- Ele informa o preço primeiro. Fazer takes custa créditos. O Claude é instruído a chamar a ação de gerar com
dryRun: true, que não faz nada, e a dizer quanto um take vai custar antes de começar um, e a nunca renderizar finais sem ser pedido. - Ele nunca aprova sem ser pedido.
sign_offregistra uma decisão em seu nome. O Claude é instruído a usá-lo só quando você pediu que ele decidisse.
Prompts #
Quatro prompts carregam um método de trabalho para serviços comuns: break_down_episode, process_feedback, work_on_step e
check_continuity. Veja Prompts e método de trabalho.
Com o Claude
MCPO seu próprio Claude faz isso via MCP, em seu nome e com a sua função:
find_actionsBusca tudo o que a API faz e devolve as ações que combinam, com seus parâmetros.
Peça: Ache a ação que muda a regra de aprovação de uma etapa.
run_actionExecuta uma ação achada com find_actions, em seu nome, com a sua função e os seus direitos.
Peça: Escolha o segundo take do plano 5 do episódio 2.
whats_waitingLista as etapas que aguardam a sua aprovação e as notificações que você ainda não leu.
Peça: O que está aguardando por mim no Filmsquare?
list_productionsLista as produções do seu espaço de trabalho com os episódios.
Peça: Quais produções e episódios temos no Filmsquare?
get_episodeMostra as cenas e os planos de um episódio na ordem do corte, cada etapa de departamento e se os finais já podem ser renderizados.
Peça: Em que pé está o episódio 2 e quem cada etapa está esperando?
get_feedbackLê as conversas de comentários em um plano, take, episódio ou elemento, com o timecode ou a região de cada marcação.
Peça: Quais notas ainda estão abertas no episódio 2?
reply_feedbackResponde a uma conversa de comentários em seu nome e a resolve quando a nota foi tratada.
Peça: Responda à nota do plano 4 que a nova prévia corrige a linha do olhar e resolva.
view_mediaOlha um still, keyframe ou take; o vídeo volta como o pôster mais um link de download.
Peça: Mostre o still escolhido do plano 3 e diga se bate com as referências.
upload_fileAdiciona um arquivo seu como novo take de um plano ou cena, ou como material da produção (10 MB no máximo).
Peça: Envie esta foto de referência para os materiais da produção.
get_scriptLê o tratamento mais recente do roteiro de um episódio, com os @nomes que já existem.
Peça: Leia o roteiro do episódio 2 e diga quais personagens ainda não têm @nome.
edit_scriptAltera uma cena, uma fala ou uma linha do roteiro de um episódio e salva como uma nova versão, sem reenviar o roteiro inteiro.
Peça: Reescreva a abertura da S02 do episódio 2 do jeito que acabamos de combinar e salve como uma nova versão.
submit_breakdownColoca a sua decupagem no Filmsquare: cenas, planos, diálogos, elenco, cenários e objetos de cena.
Peça: Faça a decupagem do roteiro do episódio 2 e envie. Reaproveite os @nomes que já temos.
get_continuityLado a lado, os planos escolhidos de um episódio, com as versões de elemento que cada um usa.
Peça: Monte os takes escolhidos da cena S2 para uma checagem de continuidade.
report_continuityRegistra a checagem de continuidade que você fez; cada divergência vira uma nota no take escolhido do plano.
Peça: Cheque a continuidade da cena S2 e relate as divergências que encontrar.
submit_styleColoca um guia de estilo na sua biblioteca de estilos (Create, Styles): um estilo novo ou a próxima versão de um existente.
Peça: Olhe estes stills, escreva um guia de estilo, mostre para mim e envie quando eu disser pode ir.
request_signoffPede aos aprovadores de uma etapa de departamento que aprovem; eles recebem uma notificação.
Peça: Peça aos aprovadores de a próxima etapa do episódio 2 que aprovem, com uma nota sobre o que mudou.
sign_offRegistra a sua decisão sobre uma etapa: aprovada ou ajustes pedidos. Só quando você pede que ele decida.
Peça: Aprove a próxima etapa do episódio 2 por mim.
where_does_it_goDiz em qual tela um arquivo deve ficar: o mapa, uma árvore de decisão e exemplos prontos.
Peça: Onde fica este reel de blocking?
prepare_uploadDá links de envio assinados e comandos curl prontos para até 100 arquivos do disco.
Peça: Envie os vídeos desta pasta.
add_to_visualizeColoca arquivos enviados em Storyboard, 3D ou Animatic, em planos e cenas pelo código.
Peça: Coloque o trabalho do Blender em 3D e os animatics em Animatic.
studio_analyticsPara o proprietário e os produtores: como o estúdio está indo, pela equipe, por um dia, pelos custos ou pelo e-mail do relatório como ele seria enviado.
Peça: Como a equipe foi na semana passada e quem precisa de ajuda?