Toon Studio は何をしますか？
JSONスクリプトからミックスされたMP4アニメーション映画を生成する、単一ファイルのPythonパイプライン（studio.py、stdlib + elevenlabs SDKのみ）。Windows、macOS、Linuxで動作します。GPUは不要で、ユーザーが提供するAPIキー以外のアカウントは必要ありません。
セットアップ（各マシンで一度だけ実行）
- Python 3.10以上。
pip install elevenlabs imageio-ffmpeg（ffmpegバイナリはimageio-ffmpegに同梱されています。必要に応じてFFMPEG環境変数で上書き可能）。.env.exampleを.envにコピーし、以下を記入：KIE_API_KEY（必須） - https://kie.ai から取得。画像、動画、音楽生成に対応。ELEVENLABS_API_KEY（推奨） - https://elevenlabs.io から取得。直接音声生成を行います。KIEはElevenLabs TTSを再販していますが、そのエンドポイントは度々障害が発生します。デフォルトのストーリーでは、音声ルートは直接バックエンドに送られます。- モデル選択は、2026年11月時点で測定された予算/品質のスイートスポットにデフォルト設定されています：
qwen3/pro-text-to-image（静止画、約6.4クレジット）、minimax-h3/image-to-video（クリップ、約48クレジット/6秒）、SunoV4_5（BGM）。任意のKIEモデルIDは、KIE_IMAGE_MODEL/KIE_VIDEO_MODEL/KIE_MUSIC_MODELで置き換え可能です。
ワークフロー
- スクリプト。
story.jsonを作成します（examples/moodcast-eva/story.jsonおよびstudio.pyの先頭のdocstringを参照）：タイトル、スタイル、キャラクター（名前、デザイン、音声の説明、実在の人物を漫画化するためのオプションのphoto、オプションのElevenLabsvoice_id）、シーン（説明、モーション、4～15秒の長さ、発言者付きの台詞行）、music_prompt。 または、LLMを使って下書きすることも可能：python studio.py new "子猫の騎士が黄金の鍵を見つける" --scenes 3 --out story.json - ビルド。
python studio.py build story.json --outdir my-filmステージ：キャラクターリファレンス → ストーリーボード静止画 → アニメーション → ナレーション → 音楽＋ミックス。各ステージはキャッシュされ、再実行では不足している部分のみが生成されます。 - ディレクター（オプション、推奨）。
--directorを追加すると、ストーリーボード静止画の後で一時停止します：各画像を確認し、承認するか、メモ付きで再生成（r wider shot）するか、アニメーションクレジットが消費される前に自分で画像を差し替え（s path.png）ます。インタラクティブなstdinがないエージェントでは、代わりにフォルダプロトコルを使用します：build --stop-after stillsを実行し、出力ディレクトリ内のsceneN.pngを確認/上書き（またはpython studio.py regen story.json --outdir DIR <scene#> "director's note"を実行）してから、同じビルドを再実行します。 - プロデューサー（オプション）。
--producerを追加すると、アセンブリ後の修正ループが実行されます：r 2でシーン2のクリップを再レンダリング、v 2 1でシーン2の1行目のナレーションを再生成、m 0.2でBGMを大きくして再ミックス、aで承認。 - 事前チェック（クレジット消費なし）。
python studio.py check story.jsonでスキーマを検証し、シーンごとの発話時間の適合性（推定発話秒数 vs シーンウィンドウ）を報告し、不足しているステージのKIEクレジットコストと現在の残高を見積もります。消費前に承認します。 - キャストの承認（低コスト）。
python studio.py preview story.jsonで、各固有の音声の最初の1行をpreview_<speaker>.mp3としてレンダリングします。これにより、ビデオクレジットが消費される前にユーザーが音声を承認できます。
すべてのビルドでは、MP4の横に<film>.srt（各台詞行のフィルムタイムライン上の正確な配置を示すキャプションサイドカー）も書き込まれ、デフォルトでキャプションがビデオに焼き付けられます（白文字に暗い輪郭、画面下部3分の1の位置。build --no-captionsで無効化、またはstudio.py内のCAPTION_STYLEでスタイル変更可能）。
苦労して得たモデルの事実（再導出しないこと）
- KIEタスクAPI：
POST {KIE_BASE_URL}/api/v1/jobs/createTask、本文は{"model", "input": {...}}、結果はGET /api/v1/jobs/recordInfo?taskId=...でポーリング。成功はsuccessFlag == 1。結果はdata.response.resultUrls[0]。ローカルファイルのアップロード先はhttps://kieai.redpandaai.co/api/file-base64-upload（JSON base64）であり、api.kie.aiではありません。 - 参照画像：nano-bananaファミリーは
image_input（URLのリスト）を読み取ります。image_urlsフィールドは黙って無視され、指定と異なるキャラクターが生成されます。 - MiniMax H3（
minimax-h3/image-to-video）：入力はfirst_frame_url、整数の長さ4～15、解像度768Pまたは2K。このモデルはネイティブに独自のサウンドトラック（多くの場合、ボーカル付きフルミュージック）を生成します。スタジオではデフォルトでこれを無音にします（studio.py内でAMB_VOL = 0.0）。確実にクリーンな効果音であることが確認できたレンダリングでのみ音量を上げてください。 - Hailuo（
hailuo/2-3-image-to-video-pro）：image_url、文字列の長さ（"6" / "10"）、解像度768P/1080P。 - Seedance（
bytedance/seedance-2-fast）：first_frame_url、整数の長さ、generate_audio: false。 - KIE経由のSuno音楽：
POST /api/v1/generate（プレースホルダーのcallBackUrlが必要。GET /api/v1/generate/record-info?taskId=...でstatus == SUCCESSをポーリング、音声はresponse.sunoData[0].audioUrl）。 - すべてのモーションプロンプトには2つのハードルール（
studio.py内の定数NO_SPEAK、AUDIO_FX）が適用されます：キャラクターは決して口を動かさない（そうしないとオフスクリーンの台詞がリップシンクの不一致として認識される）、およびクリップのサウンドトラックに音楽や音声を含めない。
バックエンド
story.jsonの"backends"は、各プリミティブを独立してルーティングします：{"image": "kie", "video": "kie", "voice": "elevenlabs", "music": "kie"}。利用可能なバックエンド：kie（画像/動画/音楽/音声）、elevenlabs（音声のみ、直接API）、higgsfield（代替CLIバックエンド）。TOON_BACKENDまたはストーリーのbackendで指定がない限り、デフォルトはhiggsfieldです。
コストの透明性（KIEで測定、2026年11月）
| モデル | コスト | 備考 |
|---|---|---|
| qwen3/pro-text-to-image | 約6.4クレジット/画像 | 1344x768、参照機能あり、約60秒 |
| z-image | 約0.8クレジット/画像 | 低コスト、低品質 |
| nano-banana-pro | 約18クレジット/画像 | 高品質 |
| minimax-h3/image-to-video | 約48～56クレジット/6秒 | 高速（約90秒）、独自の音声を生成 |
| hailuo/2-3 i2v pro | 約45クレジット/6秒 | 約130秒 |
| seedance-2-fast | 約148.8クレジット/6秒 | 高品質なモーション |
| Suno V4_5 | 約24クレジット/曲 | フル曲、ミックスでトリミング |
ElevenLabs音声：プランによる文字数制限に従います（例：eleven_v4は約数百文字/行）。KIEの残高はGET /api/v1/chat/creditで確認できます。ビルドは毎回実行後に残りクレジットを表示します。
トラブルシューティング
- キャラクターの見た目がおかしい / 参照を無視する：参照が実際にアップロードされたか確認します（ログにタスクIDが表示されます）。nano-bananaは
image_urlsではなくimage_inputを必要とします。 - フィルムに余分な音楽や音声が含まれる：H3などによるクリップレベルのサウンドトラックが原因です。
AMB_VOL = 0.0を維持するか、クリップを再レンダリングします（非決定論的です）。 - ナレーション中のリップフラップ：NO_SPEAKルールで通常は防げます。もし1つのクリップで問題が発生した場合、その
clipN.mp4を削除してビルドを再実行するか（新しいレンダリングで通常は改善されます）、--producerとメモを付けて再レンダリングします。 - KIE音声タスクが500エラーで失敗する：
voiceをelevenlabs（直接）にルーティングします。 - ビルドの途中で生成が失敗した：同じコマンドを再実行するだけです。完了したステージは再利用され、不足しているアセットのみが再生成されます。