Toon Studio

Was macht Toon Studio?

Eine aus einer einzigen Datei bestehende Python-Pipeline (studio.py, nur Stdlib + elevenlabs SDK), die aus einem JSON-Skript einen gemischten MP4-Zeichentrickfilm erzeugt. Läuft unter Windows, macOS und Linux. Keine GPU, keine Konten außer den vom Benutzer bereitgestellten API-Schlüsseln.

Einrichtung (einmal pro Maschine durchführen)

1. Python 3.10+.
2. pip install elevenlabs imageio-ffmpeg (ffmpeg-Binärdatei ist in imageio-ffmpeg enthalten; bei Bedarf mit der Umgebungsvariablen FFMPEG überschreiben).
3. Kopieren Sie .env.example in .env und füllen Sie folgende Felder aus:
   • KIE_API_KEY (erforderlich) – von https://kie.ai – deckt Bild-, Video- und Musikgenerierung ab.
   • ELEVENLABS_API_KEY (empfohlen) – von https://elevenlabs.io – direkte Sprachgenerierung. KIE vertreibt auch ElevenLabs TTS weiter, aber dieser Endpunkt hat wiederholt Ausfälle; das Standard-Skript leitet die Sprachausgabe an das direkte Backend weiter.
   • Die Modellauswahl standardisiert auf das Budget-/Qualitätssüßpunkt vom November 2026: qwen3/pro-text-to-image (Standbilder, ~6,4 Credits), minimax-h3/image-to-video (Clips, ~48 Credits / 6 s), Suno V4_5 (Musikbett). Jede KIE-Modell-ID kann über KIE_IMAGE_MODEL / KIE_VIDEO_MODEL / KIE_MUSIC_MODEL ersetzt werden.

Arbeitsablauf

1. Skript. Schreiben Sie eine story.json (siehe examples/moodcast-eva/story.json und den Kopf-Docstring in studio.py): Titel, Stil, Charaktere (Name, Design, Sprachbeschreibung, optional photo um eine reale Person zu cartoonisieren, optionale ElevenLabs voice_id), Szenen (Beschreibung, Bewegung, Dauer 4-15 s, Dialogzeilen mit Sprecher), music_prompt. Oder entwerfen Sie eines mit einem LLM: python studio.py new "ein Kätzchen-Ritter findet einen goldenen Schlüssel" --scenes 3 --out story.json
2. Erstellen. python studio.py build story.json --outdir my-film Phasen: Charakterreferenz -> Storyboard-Standbilder -> Animation -> Voiceover -> Musik + Mix. Jede Phase wird zwischengespeichert; beim erneuten Ausführen wird nur das Fehlende generiert.
3. Direkter Modus (optional, empfohlen). Fügen Sie --director hinzu, um nach den Storyboard-Standbildern anzuhalten: Jedes Bild ansehen, dann akzeptieren, mit einer Notiz neu generieren (r weitere Einstellung) oder ein eigenes Bild einfügen (s pfad.png), bevor Animations-Credits ausgegeben werden. In einem Agenten ohne interaktives stdin verwenden Sie stattdessen das Ordnerprotokoll: build --stop-after stills, die sceneN.png im Ausgabeverzeichnis überprüfen/überschreiben (oder python studio.py regen story.json --outdir DIR <Szene#> "Regieanweisung"), dann denselben Build erneut ausführen.
4. Produzent (optional). Fügen Sie --producer für eine Nachbearbeitungsschleife hinzu: r 2 rendert Szene 2 neu, v 2 1 vertont Zeile 1 von Szene 2 neu, m 0.2 mischt mit lauterer Musik neu, a akzeptiert.
5. Vorabprüfung (keine Credits). python studio.py check story.json validiert das Schema, meldet die Sprachpassung pro Szene (geschätzte Sprechsekunden vs. Szenenfenster) und gibt die KIE-Creditkosten der fehlenden Phasen sowie den aktuellen Kontostand an – vor dem Verbrauch genehmigen.
6. Besetzung genehmigen (günstig). python studio.py preview story.json rendert die erste Zeile jeder einzelnen Stimme in preview_<sprecher>.mp3, damit der Benutzer die Stimmen genehmigen kann, bevor Videocredits ausgegeben werden.

Jeder Build schreibt außerdem <film>.srt neben die MP4 – eine Untertitel-Begleitdatei mit der genauen Platzierung jeder Zeile auf der Film-Zeitleiste – und brennt die Untertitel standardmäßig in das Video ein (weiß mit dunklem Umriss, unteres Drittel; deaktivieren mit build --no-captions oder umgestalten über CAPTION_STYLE in studio.py).

Hart erarbeitete Modellfakten (nicht neu herleiten)

• KIE-Aufgaben-API: POST {KIE_BASE_URL}/api/v1/jobs/createTask mit {"model", "input": {...}}, abfragen GET /api/v1/jobs/recordInfo?taskId=...; Erfolg = successFlag == 1; Ergebnis unter data.response.resultUrls[0]. Lokale Dateien hochladen an https://kieai.redpandaai.co/api/file-base64-upload (JSON base64), NICHT an api.kie.ai.
• Referenzbilder: Die nano-banana-Familie liest image_input (eine Liste von URLs); das Feld image_urls wird stillschweigend ignoriert und erzeugt vom Briefing abweichende Charaktere.
• MiniMax H3 (minimax-h3/image-to-video): Eingabe benötigt first_frame_url, ganzzahlige Dauer 4-15, Auflösung 768P oder 2K. Es generiert standardmäßig einen EIGENEN Soundtrack – oft mit voller Musik und Gesang – den das Studio standardmäßig stumm schaltet (AMB_VOL = 0.0 in studio.py). Erhöhen Sie ihn nur für Renderings, die Sie als saubere Soundeffekte verifiziert haben.
• Hailuo (hailuo/2-3-image-to-video-pro): image_url, String-Dauer ("6"/"10"), Auflösung 768P/1080P.
• Seedance (bytedance/seedance-2-fast): first_frame_url, ganzzahlige Dauer, generate_audio: false.
• Suno-Musik über KIE: POST /api/v1/generate (eine Platzhalter-callBackUrl ist erforderlich; abfragen GET /api/v1/generate/record-info?taskId=... für status == SUCCESS, Audio unter response.sunoData[0].audioUrl).
• Alle Bewegungsaufforderungen enthalten zwei feste Regeln (Konstanten NO_SPEAK, AUDIO_FX in studio.py): Charaktere bewegen nie ihre Lippen (Dialog außerhalb des Bildschirms würde sonst als defekter Lippensync gelesen) und keine Musik/Stimmen in Clip-Soundtracks.

Backends

story.json "backends" leitet jede Fähigkeit unabhängig weiter: {"image": "kie", "video": "kie", "voice": "elevenlabs", "music": "kie"}. Verfügbar: kie (Bild/Video/Musik/Sprache), elevenlabs (nur Sprache, direkte API), higgsfield (alternatives CLI-Backend). Standard für alles ist higgsfield, es sei denn TOON_BACKEND oder die story backend-Angabe legen etwas anderes fest.

Kostentransparenz (gemessen auf KIE, November 2026)

Modell	Kosten	Hinweise
qwen3/pro-text-to-image	~6,4 Credits/Bild	1344x768, Referenzen funktionieren, ~60 s
z-image	~0,8 Credits/Bild	günstiger, geringere Qualität
nano-banana-pro	~18 Credits/Bild	Premium-Qualität
minimax-h3/image-to-video	~48-56 Credits / 6 s	schnell (~90 s), erzeugt eigenen Ton
hailuo/2-3 i2v pro	~45 Credits / 6 s	~130 s
seedance-2-fast	~148,8 Credits / 6 s	Premium-Bewegung
Suno V4_5	~24 Credits/Song	vollständiger Song, Mix kürzt ihn

ElevenLabs-Stimmen: Plancharaktere (z.B. eleven_v4 ~ ein paar hundert Zeichen/Zeile). Überprüfen Sie GET /api/v1/chat/credit für den KIE-Kontostand; der Build gibt die nach jedem Durchlauf verbleibenden Credits aus.

Fehlerbehebung

• Charaktere sehen falsch aus / ignorieren die Referenz: Prüfen Sie, ob die Referenz tatsächlich hochgeladen wurde (das Log zeigt die Aufgaben-ID); nano-banana benötigt image_input, nicht image_urls.
• Zusätzliche Musik oder Stimmen erscheinen im Film: Clip-Level-Soundtrack von H3 oder ähnlich – behalten Sie AMB_VOL = 0.0 bei oder rendern Sie den Clip neu (er ist nicht deterministisch).
• Lippenbewegung über Erzählung: Die Regel NO_SPEAK gilt normalerweise; wenn ein Clip durchrutscht, löschen Sie die entsprechende clipN.mp4 und führen Sie den Build erneut aus (ein frisches Rendering hält sich in der Regel daran), oder rendern Sie mit --producer und einem Hinweis neu.
• KIE-Sprachaufgaben schlagen mit 500 fehl: Leiten Sie voice an elevenlabs (direkt) weiter.
• Eine Generierung ist mitten im Build fehlgeschlagen: Führen Sie einfach denselben Befehl erneut aus; abgeschlossene Phasen werden wiederverwendet, nur das fehlende Asset wird neu generiert.