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开头的文档字符串）：标题、风格、角色（名称、外观、 语音描述，可选photo用于将真人卡通化，可选 ElevenLabsvoice_id）、场景（描述、运动、持续时间 4-15 秒、 包含说话者的台词）、音乐提示。 或者用 LLM 草拟剧本：python studio.py new "一只小猫骑士找到一把金钥匙" --scenes 3 --out story.json - 构建。
python studio.py build story.json --outdir my-film阶段：角色参考 -> 分镜静态图 -> 动画 -> 配音 -> 音乐 + 混音。每个阶段都会缓存；重新运行只会生成缺失的部分。 - 导演模式（可选，推荐）。 添加
--director会在分镜静态图后暂停： 查看每张图，然后接受、根据备注重新生成（r 更广的镜头），或者在 花费动画积分之前将自己的图片放进去（s path.png）。在没有 交互式标准输入的 agent 中，请改用文件夹协议：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验证模式，报告每个场景的语音时长匹配（估计的语音 秒数 vs 场景窗口），并报价缺失阶段所需的 KIE 积分成本以及 当前余额——在花费之前批准。 - 批准配音阵容（低成本）。
python studio.py preview story.json将每个不同角色的第一行台词渲染为preview_<说话者>.mp3，以便用户在花费任何视频积分之前批准语音。
每次构建还会在 MP4 旁写入 <film>.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。它会原生生成自己 的配乐——通常包含完整的音乐和人声——工作室默认会将其静音 （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）。 - 所有运动提示都附带两条硬性规则（
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（直接）。 - 构建过程中某阶段生成失败：只需重新运行相同的命令；已完成 的阶段会被重用，只有缺失的资源会重新生成。