Filmsquare AjudaDocumentação

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.

Atualizado em 8 min de leitura.md

Nesta página
  1. As ferramentas nomeadas
  2. Para onde vai a mídia
  3. find_actions e run_action
  4. Exemplos
  5. Quando a API recusa
  6. O que fica de fora de propósito
  7. Segurança
  8. Prompts

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 #

FerramentaO que fazPrecisa de
whats_waitingEtapas de departamento aguardando a sua aprovação, e as suas notificações não lidas. O lugar de começar—
list_productionsAs produções do espaço de trabalho com os seus episódios—
get_episodeUm 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 renderizadosepisode_id
get_feedbackConversas 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 anteriorestarget_type, target_id
reply_feedbackResponde 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 confirmathread_id, body
view_mediaUm 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 downloadasset_version_id
upload_fileUm 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_goEm qual tela um arquivo deve ficar: o mapa, uma árvore de decisão e exemplos prontos. Leia quando você citar uma tela—
prepare_uploadURLs de envio assinadas e comandos curl prontos para até 100 arquivos do disco, para os bytes nunca passarem pela conversa. Use para todo vídeofiles
add_to_visualizePõ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 nadaepisode_id, items
get_scriptO último tratamento do roteiro do episódio, e os @handles do elenco, cenários e objetos de cena que já existemepisode_id
edit_scriptAltera 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 juntoepisode_id, base_rev, edits
submit_breakdownPõ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çãoepisode_id, breakdown
get_continuityA 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 gratuitaepisode_id
report_continuityRegistra uma checagem visual de continuidade; cada divergência vira uma nota no take escolhidoepisode_id, seen, issues
submit_styleColoca 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 artistaname, guide
request_signoffPede aos aprovadores de um departamento que aprovem a etapa de um episódio; eles recebem uma notificaçãoepisode_id, department
sign_offRegistra 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 decidisseepisode_id, department, decision
studio_analyticsPara 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úmerosview

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ê temVai paraCom
Render clay ou still de um plano, com lente, altura e movimentoStoryboard → 3D, no planoadd_to_visualize
Clipe do Blender de um plano, um take ou uma cenaStoryboard → 3D, no que ele cobreadd_to_visualize
Animatic de uma cena, sequência ou episódioStoryboard → Animaticadd_to_visualize
Vídeo de prévia ou final de um planoStoryboard → Shots, como um takeupload_file
Imagem de referência ou mood boardHome → Filesupload_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.

  1. find_actions busca 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.
  2. run_action executa uma pelo nome, com path_params (não o espaço de trabalho), query e body como 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ê dizEle também busca
pick, chooseselect
note, notes, comment, comments, feedbackthread, message
replymessage
rendergeneration, generate
makecreate, generate
new, addcreate
remove, deletearchive
signsignoff
approvesignoff, approval
cast, character, propelement
setelement, location
production, productionsproject
crewmember, steps
costcosts, estimate
priceestimate
prompt, preview, dry rungenerate
kosten, schatting, prijs (neerlandês)generate, estimate
mismatchcontinuity
model, modelsmodels, acceptance, routing

As ações novas da API aparecem em find_actions no momento em que saem. Nenhuma ferramenta nova é necessária.

Exemplos #

ParaBuscaAçã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_off registra 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

MCP

O seu próprio Claude faz isso via MCP, em seu nome e com a sua função:

  • find_actions

    Busca 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_action

    Executa 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_waiting

    Lista 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_productions

    Lista 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_episode

    Mostra 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_feedback

    Lê 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_feedback

    Responde 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_media

    Olha 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_file

    Adiciona 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_script

    Lê 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_script

    Altera 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_breakdown

    Coloca 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_continuity

    Lado 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_continuity

    Registra 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_style

    Coloca 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_signoff

    Pede 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_off

    Registra 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_go

    Diz 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_upload

    Dá links de envio assinados e comandos curl prontos para até 100 arquivos do disco.

    Peça: Envie os vídeos desta pasta.

  • add_to_visualize

    Coloca 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_analytics

    Para 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?

Conectar o Claude 5.1

Esta página em Markdown: /docs/pt-br/claude/tools.md