toon-studio

Toon Studio

Uma pipeline Python de arquivo único (studio.py, apenas stdlib + SDK elevenlabs) que produz um filme de desenho animado MP4 mixado a partir de um roteiro JSON. Funciona no Windows, macOS e Linux. Sem GPU, sem contas além das chaves de API fornecidas pelo usuário.

Configuração (faça isso uma vez por máquina)

1. Python 3.10+.
2. pip install elevenlabs imageio-ffmpeg (o binário ffmpeg é fornecido com imageio-ffmpeg; substitua pela variável de ambiente FFMPEG, se desejado).
3. Copie .env.example para .env e preencha:
   • KIE_API_KEY (obrigatório) - de https://kie.ai - cobre geração de imagem, vídeo e música.
   • ELEVENLABS_API_KEY (recomendado) - de https://elevenlabs.io - geração de voz direta. A KIE também revende TTS da ElevenLabs, mas esse endpoint tem falhas recorrentes; o roteiro padrão roteia a voz para o backend direto.
   • As seleções de modelo padrão escolhem o ponto ideal entre custo e qualidade medido em novembro de 2026: qwen3/pro-text-to-image (imagens estáticas, ~6,4 créditos), minimax-h3/image-to-video (clipes, ~48 créditos / 6 s), Suno V4_5 (fundo musical). Qualquer ID de modelo KIE pode ser substituído via KIE_IMAGE_MODEL / KIE_VIDEO_MODEL / KIE_MUSIC_MODEL.

Fluxo de Trabalho

1. Roteiro. Escreva um arquivo story.json (veja examples/moodcast-eva/story.json e o docstring de cabeçalho em studio.py): título, estilo, personagens (nome, design, descrição de voz, opcional photo para transformar uma pessoa real em desenho animado, opcional voice_id da ElevenLabs), cenas (descrição, movimento, duração 4-15 s, falas com locutor), music_prompt. Ou crie um com um LLM: python studio.py new "um gatinho cavaleiro encontra uma chave dourada" --scenes 3 --out story.json
2. Construir. python studio.py build story.json --outdir meu-filme Etapas: referência do personagem -> storyboard -> animação -> narração -> música + mixagem. Cada etapa é armazenada em cache; reexecutar gera apenas o que está faltando.
3. Diretor (opcional, recomendado). Adicione --director para pausar após as imagens do storyboard: visualize cada imagem, depois aceite, regenere com uma anotação (r plano mais aberto) ou substitua por sua própria imagem (s path.png) antes que os créditos de animação sejam gastos. Em um agente sem stdin interativo, use o protocolo de pasta: build --stop-after stills, revise/substitua sceneN.png no diretório de saída (ou python studio.py regen story.json --outdir DIR <cena#> "anotação do diretor"), então execute o mesmo build novamente.
4. Produtor (opcional). Adicione --producer para um loop de correção pós-montagem: r 2 renderiza novamente o clipe da cena 2, v 2 1 regrava a fala 1 da cena 2, m 0.2 remixa com fundo musical mais alto, a aceita.
5. Verificar primeiro (sem créditos). python studio.py check story.json valida o esquema, relata a adequação da fala por cena (segundos estimados de fala vs. janela da cena) e informa o custo em créditos KIE das etapas ausentes mais o saldo atual - aprove antes de gastar.
6. Aprovar o elenco (barato). python studio.py preview story.json renderiza a primeira linha de cada voz distinta para preview_<locutor>.mp3 para que o usuário aprove as vozes antes de qualquer crédito de vídeo ser gasto.

Cada build também escreve <filme>.srt ao lado do MP4 - um arquivo lateral de legendas com o posicionamento exato de cada fala na linha do tempo do filme - e queima as legendas no vídeo por padrão (branco com contorno escuro, terço inferior; desabilite com build --no-captions, ou reestilize via CAPTION_STYLE no studio.py).

Fatos dos modelos (não redescubra)

• API de tarefa KIE: POST {KIE_BASE_URL}/api/v1/jobs/createTask com {"model", "input": {...}}, consulte GET /api/v1/jobs/recordInfo?taskId=...; sucesso = successFlag == 1; resultado em data.response.resultUrls[0]. Faça upload de arquivos locais para https://kieai.redpandaai.co/api/file-base64-upload (base64 JSON), NÃO para api.kie.ai.
• Imagens de referência: a família nano-banana lê image_input (uma lista de URLs); o campo image_urls é silenciosamente ignorado e produz personagens fora do briefing.
• MiniMax H3 (minimax-h3/image-to-video): a entrada recebe first_frame_url, duração inteira 4-15, resolução 768P ou 2K. Ele nativamente gera SUA PRÓPRIA trilha sonora - geralmente música completa com vocais - que o estúdio silencia por padrão (AMB_VOL = 0.0 no studio.py). Aumente apenas para renderizações que você verificou que são efeitos sonoros limpos.
• Hailuo (hailuo/2-3-image-to-video-pro): image_url, duração string ("6"/"10"), resolução 768P/1080P.
• Seedance (bytedance/seedance-2-fast): first_frame_url, duração inteira, generate_audio: false.
• Música Suno via KIE: POST /api/v1/generate (um callBackUrl de espaço reservado é obrigatório; consulte GET /api/v1/generate/record-info?taskId=... para status == SUCCESS, áudio em response.sunoData[0].audioUrl).
• Todos os prompts de movimento carregam duas regras fixas (constantes NO_SPEAK, AUDIO_FX no studio.py): os personagens nunca movem os lábios (diálogo fora da tela seria lido como sincronia labial quebrada) e nenhuma música/voz nas trilhas sonoras dos clipes.

Backends

O story.json "backends" roteia cada primitiva independentemente: {"image": "kie", "video": "kie", "voice": "elevenlabs", "music": "kie"}. Disponíveis: kie (imagem/vídeo/música/voz), elevenlabs (apenas voz, API direta), higgsfield (backend CLI alternativo). O padrão para tudo é higgsfield a menos que TOON_BACKEND ou backend da história diga o contrário.

Transparência de custos (medido na KIE, novembro de 2026)

Modelo	Custo	Observações
qwen3/pro-text-to-image	~6,4 créditos/img	1344x768, referências funcionam, ~60 s
z-image	~0,8 créditos/img	mais barato, fidelidade inferior
nano-banana-pro	~18 créditos/img	qualidade premium
minimax-h3/image-to-video	~48-56 créditos / 6 s	rápido (~90 s), cria seu próprio áudio
hailuo/2-3 i2v pro	~45 créditos / 6 s	~130 s
seedance-2-fast	~148,8 créditos / 6 s	movimento premium
Suno V4_5	~24 créditos/música	música completa, a mixagem a corta

Vozes ElevenLabs: plano de caracteres (exemplo eleven_v4 ~ algumas centenas de caracteres/linha). Verifique GET /api/v1/chat/credit para o saldo KIE; o build exibe créditos restantes após cada execução.

Solução de problemas

• Personagens parecem errados / ignoram a referência: verifique se a referência foi realmente enviada (o log mostra o ID da tarefa); nano-banana precisa de image_input, não image_urls.
• Música ou vozes extras aparecem no filme: trilha sonora de nível de clipe do H3 ou similar - mantenha AMB_VOL = 0.0, ou renderize o clipe novamente (ele não é determinístico).
• Lábios se movendo sobre a narração: a regra NO_SPEAK geralmente funciona; se um clipe escapar, exclua esse clipN.mp4 e reexecute o build (uma nova renderização geralmente resolve), ou renderize novamente com --producer e uma anotação.
• Tarefas de voz KIE falham com 500: roteie voice para elevenlabs (direto).
• Uma geração falhou no meio do build: apenas reexecute o mesmo comando; as etapas concluídas são reutilizadas, apenas o ativo ausente é regenerado.