Toon Studio 動畫工作室 是做什麼的？
一個單一檔案的 Python 管線（studio.py，僅使用標準函式庫 + elevenlabs SDK），
可以從 JSON 腳本產出完整的混合 MP4 卡通電影。可在 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（背景音樂）。任何 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 更寬的鏡頭），或用自己的圖片替換（s path.png），然後才花費 動畫額度。在沒有互動式 stdin 的代理程式中，請改用 資料夾協定：先執行build --stop-after stills，在輸出目錄中檢視/覆寫sceneN.png（或執行python studio.py regen story.json --outdir DIR <場景編號> "導演備註"），然後重新執行相同的建構指令。 - 製作人模式（可選）。 加上
--producer可進入後期組裝修復迴圈：r 2重新渲染場景 2 的片段，v 2 1重新配音場景 2 的第 1 行對白，m 0.2以更響亮的背景音樂重新混音，a接受。 - 先檢查（不花費額度）。
python studio.py check story.json驗證結構，報告每個場景的語音時間是否符合（估計語音秒數 與場景時間窗的比較），並估算缺少階段的 KIE 額度成本以及 當前餘額——在花費前進行批准。 - 批准角色陣容（低成本）。
python studio.py preview story.json會渲染每個不同語音的第一行對白，輸出為preview_<發言者>.mp3，讓使用者可以在花費任何影片額度前先批准語音。
每次建構還會在 MP4 旁寫入 <影片名稱>.srt——這是一個字幕側邊檔案，
包含每行對白在影片時間軸上的確切位置——並預設將字幕
燒錄到影片中（白色、深色外框、位於下方三分之一處；可透過
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。它原生會生成自己的 音軌——通常是帶有人聲的完整音樂——工作室預設會將其靜音（AMB_VOL = 0.0在 studio.py 中）。僅在您已確認渲染結果是乾淨音效時才調高此值。 - 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）。 - 所有動作提示都帶有兩條硬性規則（在 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 約幾百個字元/行）。
可透過 GET /api/v1/chat/credit 查詢 KIE 餘額；建構指令會在每次執行後
印出剩餘額度。
故障排除
- 角色看起來不對 / 忽略參考：檢查參考是否確實上傳成功（日誌中會顯示任務 ID）；
nano-banana 需要
image_input，而非image_urls。 - 影片中出現額外的音樂或語音：來自 H3 或類似模型的片段層級音軌——
請保持
AMB_VOL = 0.0，或重新渲染該片段（結果是非確定性的）。 - 旁白時出現嘴部動作：NO_SPEAK 規則通常有效；如果某個片段
漏掉了，請刪除該
clipN.mp4並重新執行建構（新的渲染 通常會遵守規則），或使用--producer加上備註重新渲染。 - KIE 語音任務失敗並顯示 500 錯誤：請將
voice路由至elevenlabs（直接）。 - 建構過程中某個階段生成失敗：只需重新執行相同的指令；已完成的階段 會被重複使用，只有缺少的資源會重新生成。