zhishu-seedance

概述

Zhishuai Doubao Seedance 视频生成

连接用户自己的视频生成服务（https://www.zhishuai.net）。模型二选一：

两者共用同一套四种内容模式（文生 / 首帧图生 / 首尾帧 / 多模态参考）+ 媒体规格 + 分辨率取值，所有模式互斥。官方文档：https://doc.zhishuai.net/?menu=api （Seedance 视频生成节）。

何时使用

• 用户要求"用 Seedance / doubao-seedance / Seedance 2.5 / Seedance 2.0 生成视频"。
• 用户明确指定模型（"用 2.0 便宜点""要 30 秒，用 2.5"），或没指定时按默认 2.5 走并让用户在卡片上确认。
• 用户描述"按这张图做视频""首帧是 A、尾帧是 B""参考这张产品图 + 这段 BGM 生成"。
• 用户提供 task_id（形如 task_xxx）要求"查状态""等它完""取消它"。
• 看到末尾帧 PNG 需求（return_last_frame）、加水印需求、输出 mov 给剪辑软件等，也归本 skill。
• 注意：与 MiniMax-H3 分属不同 skill，路径/请求结构/状态枚举都不同；若用户提到 H3 请引导其使用 zhishuai-h3 skill。

交互式生成：先让用户选，再提交（标准流程）

⚠️ 强制第 0 步：每次生成前，先确认 API Key 已配置

这是不可跳过的前置动作，必须在「问画面描述 / 弹选项卡片」之前完成：

BASH复制

python <skill>/scripts/create_video.py --check-key

• 退出码 0（打印 KEY_STATUS=OK）→ 已配置，直接进入下面的标准流程。
• 退出码 2（打印 KEY_STATUS=UNSET）→ 停止，按下方「首次使用」弹框要 Key，不要直接跑创建脚本。

真实 Key 写入后，从头按标准流程走一遍即可（配置不丢，无需重复要 Key）。

用户说"生成视频"时，禁止直接提交任务。标准动作：

1. 问画面描述：用户没给清楚就先问一句（自由文本）。
2. 弹选项卡片让用户点选：用 AskUserQuestion 一次性问 5 项（模型 → 生成模式 → 时长 → 画面比例 → 分辨率），选项直接取自 options.json（跑 python scripts/interactive.py --spec 可拿 JSON）。模型是第 1 项，用户点选后才决定后面哪些选项可见：选 Seedance 2.0 时，options.json 里标了 models 的选项（30 秒、联网搜索）不要出现在卡片里。音频默认生成、附加选项用户没提就按默认走，不必挨个问。选项卡片不显示价格（老板要求），但弹卡片前仍要在正文里用一句话做消费确认（如「480p 一条约 ¥3.4、720p 约 ¥7.6、1080p 约 ¥13.5，按 5 秒计，智枢实际账单为准」），用户点选即视为同意。
3. 复述需求 + 风险提示（费用 + 成片链接 24h 过期），用户点头后再执行。
4. 提交后立刻把 task_id 给用户，并说明预计等待时长（实测 5s/720p 约 2~3 分钟）。
5. 出片后立即下载到本地（链接限时 24 小时），再用 present_files 交付。

配套脚本：

python scripts/interactive.py --spec     # 查看所有可选项与合法取值（JSON）
python scripts/interactive.py            # 终端里一步步选，最后给出可直接执行的命令
python scripts/interactive.py 
  --answers "model=doubao-seedance-2-5-260628,mode=t2v,duration=10,ratio=9:16,resolution=720p,generate_audio=on,extras=none" 
  --prompt "一只猫"                        # 非交互拼命令；i2v 加 --image URL，i2vfl/r2v 加 --media-urls "URL1 URL2"

options.json 字段说明：model 二选一（doubao-seedance-2-5-260628 默认 / doubao-seedance-2.0）；mode 四选一（t2v 文生 / i2v 首帧 / i2vfl 首尾帧 / r2v 多模态参考）；extras 可多选（last_frame / web_search / mov / watermark）。

按模型过滤：任一 option 都可带 models 数组，表示该选项只对列出的模型生效。目前已标注：时长 30 秒、extras 的 web_search → 仅 doubao-seedance-2-5-260628。interactive.py 会按已选模型自动过滤并提示隐藏了哪些项；--answers 里给到不匹配的取值会直接报错。加新模型只改 options.json 的 model 选项 + scripts/common.py 的 MODEL_PROFILES。

媒体 URL 的拼装规则在 media_inputs 节。edit / extend 子任务不在卡片里（需要参考视频），走命令行 --omni-task-type。

模型选择（2.5 / 2.0）

用户没指定时默认 doubao-seedance-2-5-260628（config.json 的 model 字段），并在卡片里让用户确认。命令行显式指定：

--model doubao-seedance-2-5-260628   # Seedance 2.5（默认）
--model doubao-seedance-2.0          # Seedance 2.0

差异与自动校验（脚本内置，见 scripts/common.py 的 MODEL_PROFILES）：

• 选 2.0 时，duration 超出 15 秒会本地直接报错（不发请求）；选 2.0 又传 --web-search 只打印警告不拦截。
• 传了不在已知列表里的 model（如自定义别名）会跳过模型差异校验并打印提示，交由服务端判定，便于网关新增模型时直接试。

首次使用：交互配置 API Key

API Key 由用户自行提供，绝不写死在代码里。三处取值优先级：命令行 --api-key > 环境变量 ZHISHUAI_SEEDANCE_API_KEY > skill 根目录 config.json 的 api_key（推荐，一次配置长期复用）。

--check-key 返回 UNSET 时的 agent 标准动作：

1. 用 AskUserQuestion 弹带输入框的卡片（header: 配置Key），问题里说明"请粘贴 www.zhishuai.net API Key（以 sk- 开头）"，options 给两项：我已在输入框填入 Key / 暂不配置，取消本次生成。用户把 Key 贴在「其他」自由输入框里提交。
2. 校验以 sk- 开头；不符合则再次弹框要求重填，不要写入。
3. 保存：python scripts/create_video.py --api-key <KEY> --save-key（脚本会拒绝空值/占位符/非 sk- 开头的值）。
4. 回到第 0 步复测 --check-key 应得 OK，继续标准流程。

安全提示：Key 只写入本地 config.json，不要回显到对话或日志。

配置文件路径：<skill 目录>/config.json，本机实际为 C:UsersAdministrator.workbuddyskillszhishu-seedance__skillhubconfig.json。

工作流

创建视频

文生视频（最简）：

python <skill>/scripts/create_video.py --prompt "一只猫在花园里追蝴蝶，阳光明媚，慢动作"

可选：--model <doubao-seedance-2-5-260628|doubao-seedance-2.0>、--duration <4~30 或 -1，2.0 上限 15>、--resolution <480p|720p|1080p>、--ratio <16:9|...|adaptive>、--no-generate-audio、--output-format mp4|mov、--return-last-frame、--watermark、--seed <int>、--api-key <KEY>。

首帧图生视频：

python <skill>/scripts/create_video.py 
  --prompt "海浪拍打礁石，镜头缓慢推进" 
  --image "https://example.com/first-frame.jpg"

或等价写法：

python <skill>/scripts/create_video.py 
  --prompt "海浪拍打礁石" 
  --image-url first_frame=https://example.com/first-frame.jpg

首尾帧图生视频（必须在 metadata.content 里成对给出）：

python <skill>/scripts/create_video.py 
  --prompt "花朵从含苞到绽放的全过程" 
  --image-url first_frame=https://example.com/bud.jpg 
  --image-url last_frame=https://example.com/bloom.jpg

⚠️ 实测约束（2026-09-11 全参数测试发现）：首帧 / 首尾帧模式下显式传 ratio 会被服务端拒绝

（InvalidParameter.TaskTypeConstraint：For first-frame or first-last-frame generation, the output ratio follows the first-frame image）。

输出比例由首帧图决定，要么不传 ratio，要么传 adaptive。

多模态参考生视频（1~9 张参考图 + 可选参考视频 + 可选参考音频；音频不可单独传）：

python <skill>/scripts/create_video.py 
  --prompt "[图1]的产品展示广告，[音频1]作为背景音乐" 
  --image-url reference_image=https://example.com/product.jpg 
  --audio-url reference_audio=https://example.com/bgm.mp3

联网搜索增强：

python <skill>/scripts/create_video.py 
  --prompt "展示 2026 年最新的太空探索进展" 
  --web-search

显式指定子任务类型（仅在你明确知道走哪种任务时用；官方参数名 omni_reference_task_type）：

--omni-task-type reference   # 参考生视频（ratio / duration 无特殊限制）
--omni-task-type edit        # 视频编辑（需 reference_video 且 ratio=adaptive、duration=-1）
--omni-task-type extend      # 视频延长（需 reference_video，ratio=adaptive）
--omni-task-type auto        # 默认，让模型自动判定

脚本已内置官方约束校验：edit 时 ratio 非 adaptive 或 duration 非 -1 会本地直接报错（不发请求）；extend 时 ratio 非 adaptive 同样拦截。指定后若与模型实际判定不一致，服务端仍可能异步报错（错误码 InvalidParameter.TaskTypeMismatch）。

脚本打印 task_id / status，task_id 即后续查询用的 ID。

查询状态（按 ID）

python <skill>/scripts/query_video.py --task-id <task_id>

打印当前 status、成片 URL；如创建时设过 --return-last-frame 还会打印尾帧 PNG 地址。可加 --raw 看原始 JSON。

响应结构实测（2026-09-11 修复）：该网关查询响应是双层包装——

外层 data 是平台包装（status=SUCCESS/IN_PROGRESS 大写、progress 百分比、result_url），

模型任务本体在 data.data（status=succeeded/running 小写官方枚举、content.{video_url,last_frame_url}）。

flatten_task 已修复为优先取内层；进度百分比在内层缺失时由 wait_video.py 从外层补读。

等待完成（推荐，自动轮询）

python <skill>/scripts/wait_video.py --task-id <task_id>

默认每 10s 查一次、最长等 1800s（改 config.json 的 poll 或传 --interval/--timeout）。成功 → 打印视频地址（含可能的尾帧地址），退出码 0；失败/超时 → 退出码 1；取消 → 退出码 2；超时 → 退出码 4。

取消任务

python <skill>/scripts/cancel_video.py --task-id <task_id>

实测结论（2026-09-11）：取消接口正确路径是 DELETE /v1/videos/{task_id}（config.json 已修正）；对 /v1/video/generations/{task_id} 发 DELETE 会报 400 未指定模型名称（路由不存在）。

但该平台实际不支持取消：即使路径正确，服务端仍返回HTTP 501 {"code":"cancel_not_supported","message":"platform 54 does not support task cancellation"}与 HappyHorse 平台行为一致。用户要求取消时直接告知「平台不支持取消，任务会跑完并扣费，出片后可继续查询」。任务不存在时返回 400 task_not_exist。

• 文档语义（排队中→取消 / 终态→删记录）在该网关均不可用（501），保留脚本供路径探测用。

Windows 本机执行注意（Git Bash 环境）

• 本机 Git Bash shim 缺 dirname/head 等基础命令，直接跑 python xxx.py 前缀可能报 command not found。一律用托管 Python 全路径执行：

C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe <skill>/scripts/xxx.py ...

• 用哪个 Python 均可（脚本仅依赖标准库 urllib），若有托管 Python 优先用它。
• 出片链接限时 24 小时，成功后立即用 Python urllib.request.urlretrieve 下载到工作区 outputs/ 目录转存。

使用注意（对齐官方文档）

• 拿到成片视频地址后按用户需要告知、下载到本地，或直接展示。链接限时 24 小时，需及时转存。
• 请求体总大小 ≤ 64 MB；大文件用公网 URL，避免 Base64。
• prompt：中文 ≤500 字 / 英文 ≤1000 词，自动追加到 metadata.content 末尾；支持中/英/日/印尼/西/葡语。
• duration：4~30 整数，或 -1 让模型自选（官方默认 -1，config.json defaults 里是 5）；Seedance 2.0 上限 15 秒。resolution 仅 480p/720p/1080p（小写 p，官方默认 720p）；ratio 官方默认 adaptive。
• 媒体规格（官方）：
  • 图片：jpeg/png/webp/bmp/tiff/gif，宽高比 (0.4, 2.5)，宽高 (300, 6000)px，单张 ≤30MB，不支持含真人人脸的参考图。
  • 参考视频：mp4/mov，480p/720p，单段 [2,15] 秒，最多 3 段总时长 ≤15 秒，单个 ≤50MB，帧率 [24,60] FPS。
  • 参考音频：wav/mp3，单段 [2,15] 秒，最多 3 段总时长 ≤15 秒，单段 ≤15MB，不可单独传（需搭配图片/视频）。
• mov 输出为专业编码（H.264 + yuv444p + PCM），部分播放器不兼容。
• 接口状态语义、首帧/尾帧/多模态互斥约束、错误码、完整 curl 示例见 references/api.md。

错误码