Como automatizar storyboards de mininovelas com Claude Code e MCP: do roteiro ao canvas de planos com agentes de IA

Por que Claude Code e MCP transformam o storyboard de mininovelas

Este artigo foi escrito pela equipe da Say Action. As recomendações e o guia de pipeline refletem nossa experiência prática de produção conectando roteiros, storyboards, ferramentas MCP e geração de vídeo plano a plano, não sendo um benchmark independente. Com a transição das mininovelas verticais de projetos experimentais para produtoras que lançam dezenas de episódios semanais de 60 a 90 segundos, o processo de decupagem de roteiro e estruturação do storyboard tornou-se o principal gargalo técnico. Um único episódio de um minuto necessita de 10 a 14 planos dinâmicos, o que representa centenas de tomadas em uma temporada completa de 50 capítulos. O método tradicional de copiar diálogos manualmente, colar parâmetros em ferramentas isoladas de IA e digitar instruções de câmera uma a uma gera sobrecarga mental e falhas frequentes na numeração de cenas ou no ritmo dramático.

Para eliminar essas tarefas repetitivas, diretores técnicos e criadores de conteúdo estão adotando a automação com Claude Code da Anthropic e Codex da OpenAI por meio do protocolo MCP (Model Context Protocol). O MCP é um padrão aberto que possibilita aos agentes de modelos de linguagem interagir de forma controlada com ferramentas e workspaces de produção externos. Ao receber o roteiro completo, o agente interpreta o ritmo narrativo e os ganchos visuais específicos do formato vertical para redes sociais, organizando o texto em uma tabela de planos estruturada e pronta para geração.

Ao integrar o Claude Code diretamente ao servidor MCP remoto do Say Action, o diretor consegue criar projetos no canvas e preencher as linhas do storyboard com um único comando no terminal. O agente assume a distribuição mecânica das cenas e a padronização dos movimentos de câmera, liberando a equipe criativa para focar na continuidade visual e na expressão dramática dos atores no canvas infinito. Esse fluxo reduz drasticamente o tempo de pré-produção e ajuda a manter maior consistência estética em toda a série.

Arquitetura do servidor MCP do Say Action e limites de permissões

A infraestrutura MCP do Say Action funciona através de um endpoint remoto de Streamable HTTP em https://isayaction.com/api/mcp. Em vez de cookies de sessão, utiliza chaves de acesso pessoal com permissões granulares e autenticação Bearer, garantindo estabilidade e segurança tanto no terminal quanto em rotinas automáticas de script. Configurando a variável de ambiente com export ISAYACTION_API_KEY="yc_live_..." e executando claude mcp add --transport http isayaction "https://isayaction.com/api/mcp" --header "Authorization: Bearer $ISAYACTION_API_KEY", o Claude Code reconhece instantaneamente as ferramentas oficiais do Say Action.

O conjunto de ferramentas MCP do Say Action para mininovelas segue uma hierarquia bem definida. Inicialmente, as funções get_account e list_models verificam o saldo de créditos e os modelos de vídeo homologados; em seguida, create_project inicializa um projeto vertical 9:16 no canvas. Depois, ferramentas como import_script, batch_add_storyboard_cards ou set_unit_shots inserem os identificadores de tomada (Shot ID), personagens, diálogos e comandos de câmera nas linhas do storyboard. Com o perfil de especialista (?profile=expert), o agente também pode vincular nós de referência de personagens já existentes a cada tomada.

O princípio mais relevante dessa arquitetura é o limite estrito de permissões: a geração de vídeo está desacoplada da atuação autônoma do agente. Embora o Claude Code tenha autorização para analisar o roteiro, montar a grade de planos e redigir prompts visuais, ele não pode disparar tarefas de renderização de vídeo por iniciativa própria. Esse isolamento ajuda a evitar que falhas de lógica ou loops indesejados no agente iniciem dezenas de gerações dispendiosas de uma só vez. Qualquer renderização exige que o diretor humano avalie previamente os planos no canvas antes de confirmar a execução.

Modelo de prompts estruturados no Claude Code para decupagem de 12 planos

Para que o Claude Code elabore uma decupagem alinhada ao consumo em telas verticais, as instruções devem seguir a estrutura dos 12 planos em 60 segundos em vez da narrativa tradicional de cinema. Em plataformas como Kwai ou TikTok, os espectadores costumam decidir nos primeiros instantes se permanecem no vídeo; logo, é recomendável que os planos 1 e 2 apresentem um gancho impactante (Hook), geralmente um close-up dramático. Os planos 3 a 7 desenvolvem diálogos ágeis em contraplano sobre o ombro (OTS); os planos 8 a 10 concentram o clímax do conflito; e os planos 11 e 12 fecham com uma expressão de suspense (Cliffhanger) para induzir a abertura do próximo episódio.

Um prompt padrão para ser executado no terminal do Claude Code possui esta formulação: "Utilizando as ferramentas do Say Action, decupe o roteiro do episódio 1 de 'Herdeiro da Vingança' em exatamente 12 planos verticais (9:16). O plano 1 deve ser um gancho em close extremo com menos de 2 segundos. Os planos 2 a 7 devem intercalar diálogos rápidos entre os protagonistas. Os planos 8 a 10 devem retratar o clímax do confronto e os planos 11 e 12 devem encerrar com um cliffhanger de olhar enigmático. Gere uma chave idempotencyKey exclusiva para cada plano, mantenha os diálogos originais e separe os movimentos de câmera das ações físicas dos personagens. Preencha a tabela de storyboard sem acionar a geração de vídeo."

Um critério técnico indispensável na elaboração do prompt é separar claramente os comandos de câmera dos movimentos corporais dos personagens. Quando modelos geradores de vídeo recebem instruções que misturam deslocamentos de câmera e ações físicas dos atores, costumam ocorrer distorções anatômicas e borrões faciais. A instrução ao Claude Code deve usar padrões como "Dolly In 45mm Lens / Subject Min-jun turns his head sharply". Isolar a óptica cinematográfica (Dolly, Pan, Tilt, Roll, Tracking) da atuação cênica ajuda os modelos a calcular vetores de movimento mais limpos, preservando a anatomia facial.

Ao processar a solicitação, o Claude Code executa chamadas em lote à ferramenta batch_add_storyboard_cards do Say Action, montando no canvas a sequência ordenada de Shot_01 até Shot_12. Cada linha recebe o número da cena, a duração estimada (como 2,5s ou 4s), o texto da fala, a etiqueta do personagem e o prompt visual em inglês. O terminal exibe o registro da operação e o link autenticado para o canvas, possibilitando que o diretor abra o navegador e revise todo o episódio imediatamente.

Revisão humana (Human-in-the-Loop) e prévia visual de quadros-chave

Mesmo os modelos de linguagem mais avançados não conseguem prever perfeitamente a iluminação cênica, a sutileza das expressões ou os detalhes do cenário idealizados pelo diretor apenas a partir de texto. A etapa de revisão humana (Human-in-the-Loop) após a decupagem do agente é indispensável para ajudar a manter a qualidade de uma mininovela. No canvas infinito do Say Action, todas as tomadas criadas via MCP aparecem como nós visuais interativos, permitindo que a direção reorganize enquadramentos, ajuste textos e controle o ritmo com cliques simples.

Antes de autorizar a geração de vídeo, a equipe deve seguir uma lista de verificação em três etapas. Etapa 1: Validação de elenco e diálogos. Conferir se nenhuma fala foi omitida e se as etiquetas dos personagens correspondem aos nós de referência de figuração (Character Sheet). Etapa 2: Checagem da movimentação de câmera. Confirmar que não há instruções conflitantes (como aproximação e panorâmica lateral oposta no mesmo plano) para manter uma trajetória óptica coesa. Etapa 3: Prévia com quadros-chave estáticos. Antes de renderizar vídeos completos, executam-se nós econômicos como Nano Banana ou GPT Image no Say Action para gerar um quadro fixo por plano, validando o estilo visual dos 12 planos com baixo consumo de créditos.

Com os quadros-chave aprovados, cada tomada é encaminhada ao modelo de vídeo mais adequado às suas necessidades narrativas. No Say Action, é possível distribuir modelos diferentes para planos distintos: closes de diálogo com foco na sincronia labial podem ser direcionados ao MiniMax Hailuo; planos com ação dinâmica ou movimentos rápidos de câmera podem ser gerados com Kling v3 texto para vídeo ou Kling v3 Turbo texto para vídeo; e planos que exigem continuidade cenográfica refinada podem utilizar Seedance 2.0/2.5 ou Wan 3.0 (wan3.0-*). Caso uma cena precise de correção, basta regenerar aquele nó específico sem interferir nas demais tomadas já finalizadas.

Custos de tokens do agente e controle de créditos no canvas

Ao estruturar uma linha de produção com Claude Code e MCP, o criador precisa compreender sua arquitetura de custo duplo: consumo de tokens de linguagem versus créditos de geração visual. Analisar o roteiro e organizar as linhas do storyboard consome tokens do LLM (cobrados pela Anthropic ou OpenAI para o Claude Code), enquanto gerar imagens de referência e clipes de vídeo consome créditos na plataforma Say Action. Como o custo de processamento de texto é muito baixo, aperfeiçoar o roteiro e testar diferentes estruturas de 12 planos no Claude Code antes da geração visual é a maneira mais eficiente de otimizar o orçamento.

O maior perigo em automações é a ocorrência de loops infinitos causados por erros de programação. Para ajudar a mitigar esse risco, o Say Action disponibiliza um limite cumulativo de gastos (Cumulative Spending Limit) na página /access-keys para cada chave de API. Ao definir tetos como 200, 500 ou 1000 créditos, chamadas pagas adicionais são bloqueadas automaticamente caso o agente ultrapasse a cota. Além disso, cada chamada MCP exige uma chave de idempotência (idempotencyKey) de 8 a 128 caracteres, ajudando a evitar cobranças em duplicidade ou nós repetidos em caso de oscilações de rede.

Os planos de assinatura, a estimativa de créditos e as regras de reembolso seguem as definições oficiais da plataforma. Quando uma geração de vídeo falha com erro explícito do provedor do modelo, os créditos reservados são estornados para o saldo. Equipes com alta demanda ou chaves de API próprias podem conectar seus canais externos diretamente pelo passe BYOK. Para conhecer os termos completos de planos e créditos, consulte a documentação oficial: Os créditos são estimados com base nos preços do canal; o desconto final segue as faixas de preço configuradas no painel administrativo. A cobrança de vídeo por segundo é pré-autorizada pela duração solicitada; se o resultado do provedor de origem exceder essa duração, pode haver uma pequena diferença concedida como cortesia. A taxa de serviço cobre o espaço de trabalho, não o uso dos modelos. As cobranças da API do provedor são separadas. Quando o provedor confirma a falha da geração, os créditos reservados são devolvidos. Se uma interrupção de conexão deixar o resultado ou a cobrança incertos, a tarefa fica aguardando análise para evitar uma liquidação duplicada. O BYOK permite configurar o endereço da API, a chave do modelo e cabeçalhos personalizados. Ao usar OneAPI, NewAPI ou outro intermediário, selecione o protocolo OpenAI, Gemini ou Claude correspondente à API e confira os IDs dos modelos e o suporte às APIs de imagem e vídeo. Nem todo serviço ou protocolo privado funciona automaticamente. Chamadas BYOK não têm acréscimo da plataforma sobre o custo dos modelos nem descontam créditos de geração da plataforma; o espaço de trabalho e o uso do provedor são cobrados separadamente.

Conecte suas APIs e serviços de intermediação

Nas configurações do canal, informe a Base URL e a chave API. Defina o protocolo, os IDs dos modelos e os cabeçalhos conforme a documentação do provedor. Confira os modos de imagem e vídeo antes de gerar. Endereços, resoluções e entradas de quadro inicial e final dependem do canal conectado. Solicitar a adaptação de um canal não garante sua compatibilidade.

O BYOK permite configurar o endereço da API, a chave do modelo e cabeçalhos personalizados. Ao usar OneAPI, NewAPI ou outro intermediário, selecione o protocolo OpenAI, Gemini ou Claude correspondente à API e confira os IDs dos modelos e o suporte às APIs de imagem e vídeo. Nem todo serviço ou protocolo privado funciona automaticamente. Chamadas BYOK não têm acréscimo da plataforma sobre o custo dos modelos nem descontam créditos de geração da plataforma; o espaço de trabalho e o uso do provedor são cobrados separadamente.

Conecte apenas provedores de confiança e use HTTPS em produção. As solicitações passam pelo backend autenticado e utilizam os prompts, as referências e as credenciais necessários. Não coloque chaves API, senhas ou cabeçalhos com segredos em canvases públicos, capturas de tela ou pedidos de suporte.