Toon Studio

Que fait Toon Studio ?

Un pipeline Python en un seul fichier (studio.py, uniquement stdlib + SDK elevenlabs) qui produit un film d'animation MP4 mixé à partir d'un script JSON. Fonctionne sur Windows, macOS et Linux. Pas de GPU, pas de compte au-delà des clés API fournies par l'utilisateur.

Configuration (à faire une fois par machine)

1. Python 3.10+.
2. pip install elevenlabs imageio-ffmpeg (le binaire ffmpeg est fourni avec imageio-ffmpeg ; vous pouvez le remplacer via la variable d'environnement FFMPEG si souhaité).
3. Copiez .env.example vers .env et remplissez :
   • KIE_API_KEY (obligatoire) - depuis https://kie.ai - couvre la génération d'image, vidéo et musique.
   • ELEVENLABS_API_KEY (recommandé) - depuis https://elevenlabs.io - génération vocale directe. KIE revend également du TTS ElevenLabs, mais ce point d'accès subit des pannes récurrentes ; le script par défaut achemine la voix vers le backend direct.
   • Les choix de modèles par défaut privilégient le meilleur rapport budget/qualité mesuré en novembre 2026 : qwen3/pro-text-to-image (images fixes, ~6,4 crédits), minimax-h3/image-to-video (clips, ~48 crédits / 6 s), Suno V4_5 (fond musical). Tout identifiant de modèle KIE peut être substitué via KIE_IMAGE_MODEL / KIE_VIDEO_MODEL / KIE_MUSIC_MODEL.

Flux de travail

1. Script. Écrivez un fichier story.json (voir examples/moodcast-eva/story.json et le docstring d'en-tête dans studio.py) : titre, style, personnages (nom, design, description vocale, option photo pour cartooniser une personne réelle, optionnel voice_id ElevenLabs), scènes (description, mouvement, durée 4-15 s, lignes de dialogue avec intervenant), music_prompt. Ou rédigez-en un avec un LLM : python studio.py new "un chevalier chaton trouve une clé en or" --scenes 3 --out story.json
2. Build. python studio.py build story.json --outdir mon-film Étapes : référence de personnage -> storyboard images fixes -> animation -> voix off -> musique + mixage. Chaque étape est mise en cache ; une ré-exécution ne génère que ce qui manque.
3. Direct (optionnel, recommandé). Ajoutez --director pour faire une pause après les images du storyboard : visualisez chaque image, puis acceptez, régénérez avec une note (r plan plus large), ou remplacez par votre propre image (s chemin.png) avant que les crédits d'animation ne soient dépensés. Dans un agent sans stdin interactif, utilisez plutôt le protocole de dossier : build --stop-after stills, révisez/remplacez sceneN.png dans le répertoire de sortie (ou python studio.py regen story.json --outdir DIR <scene#> "note du réalisateur"), puis relancez le même build.
4. Producteur (optionnel). Ajoutez --producer pour une boucle de correction post-assemblage : r 2 re-rend le clip de la scène 2, v 2 1 re-donne la voix à la ligne 1 de la scène 2, m 0.2 re-mixe avec un fond musical plus fort, a accepte.
5. Vérifiez d'abord (sans crédits). python studio.py check story.json valide le schéma, indique l'adéquation parole par scène (secondes de parole estimées par rapport à la fenêtre de la scène), et donne le coût en crédits KIE des étapes manquantes ainsi que le solde actuel — approuvez avant de dépenser.
6. Approuvez le casting (peu coûteux). python studio.py preview story.json rend la première ligne de chaque voix distincte dans preview_<intervenant>.mp3 pour que l'utilisateur approuve les voix avant que des crédits vidéo ne soient dépensés.

Chaque build écrit également <film>.srt à côté du MP4 — un fichier de sous-titres avec le placement exact de chaque ligne sur la timeline du film — et grave les sous-titres dans la vidéo par défaut (blanc avec contour foncé, tiers inférieur ; désactivable avec build --no-captions, ou restylisable via CAPTION_STYLE dans studio.py).

Faits sur les modèles durement acquis (ne pas redécouvrir)

• API de tâche KIE : POST {KIE_BASE_URL}/api/v1/jobs/createTask avec {"model", "input": {...}}, interroger GET /api/v1/jobs/recordInfo?taskId=... ; succès = successFlag == 1 ; résultat à data.response.resultUrls[0]. Téléchargez les fichiers locaux vers https://kieai.redpandaai.co/api/file-base64-upload (base64 JSON), PAS vers api.kie.ai.
• Images de référence : la famille nano-banana lit image_input (une liste d'URLs) ; le champ image_urls est silencieusement ignoré et produit des personnages hors brief.
• MiniMax H3 (minimax-h3/image-to-video) : l'entrée prend first_frame_url, une durée entière de 4 à 15, la résolution 768P ou 2K. Il génère nativement sa PROPRE bande sonore — souvent de la musique complète avec voix — que le studio met en sourdine par défaut (AMB_VOL = 0.0 dans studio.py). Augmentez ce volume uniquement pour les rendus dont vous avez vérifié qu'il s'agit d'effets sonores propres.
• Hailuo (hailuo/2-3-image-to-video-pro) : image_url, durée en chaîne de caractères ("6"/"10"), résolution 768P/1080P.
• Seedance (bytedance/seedance-2-fast) : first_frame_url, durée entière, generate_audio: false.
• Musique Suno via KIE : POST /api/v1/generate (un callBackUrl factice est requis ; interroger GET /api/v1/generate/record-info?taskId=... pour status == SUCCESS, audio à response.sunoData[0].audioUrl).
• Toutes les consignes de mouvement comportent deux règles strictes (constantes NO_SPEAK, AUDIO_FX dans studio.py) : les personnages ne bougent jamais leurs lèvres (le dialogue hors écran serait perçu comme un lipsync mal fait) et pas de musique/voix dans les bandes sonores des clips.

Backends

story.json "backends" achemine chaque primitive indépendamment : {"image": "kie", "video": "kie", "voice": "elevenlabs", "music": "kie"}. Disponibles : kie (image/vidéo/musique/voix), elevenlabs (voix uniquement, API directe), higgsfield (backend CLI alternatif). La valeur par défaut pour tout est higgsfield sauf si TOON_BACKEND ou le backend de l'histoire dit autrement.

Transparence des coûts (mesurés sur KIE, novembre 2026)

Modèle	Coût	Remarques
qwen3/pro-text-to-image	~6,4 crédits/img	1344x768, les références fonctionnent, ~60 s
z-image	~0,8 crédits/img	moins cher, fidélité inférieure
nano-banana-pro	~18 crédits/img	qualité premium
minimax-h3/image-to-video	~48-56 crédits / 6 s	rapide (~90 s), génère son propre audio
hailuo/2-3 i2v pro	~45 crédits / 6 s	~130 s
seedance-2-fast	~148,8 crédits / 6 s	mouvement premium
Suno V4_5	~24 crédits/chanson	chanson complète, le mixage la coupe

Voix ElevenLabs : selon le plan (par exemple eleven_v4 ~ quelques centaines de caractères/ligne). Consultez GET /api/v1/chat/credit pour le solde KIE ; le build affiche les crédits restants après chaque exécution.

Dépannage

• Les personnages semblent incorrects / ignorent la référence : vérifiez que la référence a bien été téléchargée (le journal affiche l'identifiant de tâche) ; nano-banana nécessite image_input, pas image_urls.
• Musique ou voix supplémentaires dans le film : bande sonore au niveau du clip provenant de H3 ou similaire — gardez AMB_VOL = 0.0, ou re-rendez le clip (il est non déterministe).
• Bruit de bouche pendant la narration : la règle NO_SPEAK tient généralement ; si un clip dérape, supprimez ce clipN.mp4 et relancez le build (un nouveau rendu est généralement conforme), ou re-rendez avec --producer et une note.
• Les tâches vocales KIE échouent avec 500 : acheminez la voice vers elevenlabs (direct).
• Une génération a échoué en cours de route : relancez simplement la même commande ; les étapes terminées sont réutilisées, seul l'actif manquant est regénéré.