zhishu-h3

概述

MiniMax-H3 视频生成

连接你自己的视频生成服务（https://www.zhishuai.net，模型 MiniMax-H3 和 MiniMax-H3-Max）。完整支持 5 种内容模式（按 metadata.content 自动判定）：

何时使用

• 用户要求"用 H3 生成视频""用 MiniMax-H3 制作一段视频""用 H3 Max 出个极速版"。
• 用户描述"按这张图生成视频""用这两张图作为首尾帧""按这个参考视频生成"。
• 用户提供 task_id（形如 task_xxx 或 video_task_xxx）要求"查一下状态""等它完成给我地址""取消它"。
• 与 Seedance / HappyHorse 分属不同 skill，路径/参数都不同；若用户提到 Seedance 引导其使用 zhishuai-seedance，提到 HappyHorse 用 zhishuai-happyhorse。

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

这是不可跳过的前置动作，必须在「问画面描述 / 弹选项卡片」之前完成。用一条无副作用命令判断是否需要配置（不联网、不发请求）：

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

• 退出码 0（打印 KEY_STATUS=OK）→ 已配置，直接进入下面的标准流程。
• 退出码 2（打印 KEY_STATUS=UNSET）→ 停止，按下方「首次使用：弹三选项卡片」给用户弹框要 Key，不要直接跑创建脚本（否则只会拿到一段报错而不是输入框）。

即使用户没提"首次使用"，只要 --check-key 返回 UNSET，就必须先要 Key 再继续。真实 Key 写入后，从头按标准流程走一遍即可（配置不丢，无需重复要 Key）。

省事路径：当用户让"生成小兔子拔萝卜的视频"等具体任务时，可直接跑

python scripts/create_video.py --prompt "..."，

脚本会自己检测到 Key 未配并打印三选项引导卡片（输出末尾带 ONBOARD_STATUS=NEED_KEY + ONBOARD_OPTIONS=has_key,get_key,exit），

优雅退出（exit 0）。看到这串标记后，按下方「首次使用」走对应分支即可，不用先单独跑 --check-key。

首次使用：弹三选项卡片（agent 标准动作）

当脚本输出末尾出现 ONBOARD_STATUS=NEED_KEY（create/query/wait/cancel 任一脚本都可能触发），意味着检测到 API Key 尚未配置。必须用 AskUserQuestion 弹出三选项卡片，按用户选择走对应分支：

header : 配置Key
question: 「首次使用需要先配置 www.zhishuai.net API Key 才能用 MiniMax-H3 视频生成。选一个分支继续：」

options（3 项，按用户选择走）:
  ① 已有 Key，直接粘贴（label: 「① 如已有 Key，请在下方「其他补充」输入框中粘贴」）
     description: 「操作方式：点卡片底部的「其他补充…」输入框，粘贴你的 www.zhishuai.net API Key（以 sk- 开头），
                   然后直接按发送按钮发给我。我收到后会写入本地配置并继续生成。
                   Key 只保存在你本机，不会上传。」
  ② 没有 Key，去官网获取（label: 「② 还没有 Key，去 www.zhishuai.net 获取」）
     description: 「点这个选项后我会回复你一个可点击的官网链接 [https://www.zhishuai.net](https://www.zhishuai.net)。
                   打开后登录 → 「个人中心」→「API 管理」里复制或购买 Key，
                   拿到后直接粘贴回这个对话框发给我，我帮你配好接着干活。」
  ③ 没有 Key，先不配了（label: 「暂不配置，退出」）
     description: 「好的，那这次就先不配置了。之后想用时随时说一声，我再带你走配置流程。
                   有其他需要帮忙的也可以直接说。」

选项 1 分支（用户在「其他补充」输入框粘贴 Key 后发送）：

1. 用户实际行为：在 AskUserQuestion 卡片底部的「其他补充…」输入框粘贴 Key，然后按发送按钮。

（由于「其他补充」输入后上方选项按钮会变灰，用户通常不会点选「①」，而是直接发送。）

1. agent 收到一段以 sk- 开头的文本，即视为用户走「选项 1」分支。
2. agent 先校验：以 sk- 开头、长度合理（≥ 16）。校验失败则让用户重发，不要回显完整的错误 Key。
3. 执行一次性保存命令：

   python scripts/create_video.py --api-key "<KEY>" --save-key

脚本会拒绝写入非法/占位符值，并以 sk- 开头校验。成功会打印「配置已保存」。

1. 回到「强制第 0 步」重新 --check-key 应得 OK，再继续标准生成流程（同一次对话内无缝衔接，不用用户重复操作）。

选项 2 分支（用户选了 ②）：

1. 回复中必须包含可点击的官网链接：用 markdown 链接格式 [www.zhishuai.net](https://www.zhishuai.net)，

WorkBuddy 客户端会自动渲染成可点击链接，用户点链接即用系统浏览器打开。

1. 给出清晰步骤：「打开 www.zhishuai.net 登录 → 个人中心 → API 管理 → 复制或购买 Key」。
2. 提示用户拿到 Key 后直接粘贴回对话框发给你（不再弹卡片，直接走选项 1 的保存流程）。
3. 不要反复弹同一张选项卡片打扰用户。
4. 可选增强：用 WebFetch 工具抓一下官网首页，确认服务可用后再把链接给用户（避免服务宕机时给出错误链接）。

选项 3 分支（用户选了 ③）：

1. 礼貌回一句（不复述三选项原文），比如「好的，那这次就先不配置了。之后想用随时说一声，我再带你走配置流程。有其他需要帮忙的也可以直接说。」
2. 不要再追问、不要尝试调用生成脚本、不要做任何"补救"动作——用户已经明确退出了。

安全提示：API Key 只写入本地 config.json，不要回显到对话、报告或日志；提醒用户妥善保管，勿外泄。

附：Key 也可经以下任一方式提供（优先级：命令行 > 环境变量 > config.json）：

1. 命令行 --api-key <KEY>
2. 环境变量 ZHISHUAI_H3_API_KEY=<KEY>
3. config.json 的 api_key 字段（推荐，一次配置长期复用）

配置文件路径：<skill 目录>/config.json，即~/.workbuddy/skills/zhishu-h3__skillhub/config.json（目录名是 zhishu-h3__skillhub，不带 "ai"）。

交互式生成：多轮选项卡片，逐项确认（标准流程）

用户说"做个视频"时，禁止直接提交任务。标准动作是像 HappyHorse 那样弹出多轮 AskUserQuestion 卡片，每轮只问一个问题，顶部带当前需求上下文，必填项必须选、非必填项可跳过。

步骤

1. 确认画面描述：如果用户已经给了（如"小狗看书"），直接用；否则先弹一个自由文本问题要描述。
2. 逐轮弹单选卡片：按 options.json 里的 questions 顺序，每个问题一轮 AskUserQuestion。

卡片顶部用一句话总结已确定的上下文，例如：

「小狗看书」本次走【文生视频 t2va】，时长想要多长？

「小狗看书」本次走【文生视频 t2va】+ 15 秒，画面比例选哪个？

⚠️ 禁止提前写水印状态：加不加水印是最后一轮才让用户选的，之前几轮（时长/比例/分辨率）的卡片标题里不得出现「不加水印」等水印字样。

1. 每个卡片的选项必须直接取自 options.json 对应问题的 options：
   • label 作为卡片里显示的选项文字（如 6 秒、16:9 横屏、2K）
   • desc 作为选项说明（如 通用默认、最通用、最高画质）
   • 非必填问题（required: false，如水印）允许用户点「跳过」走默认值
2. 收集完所有选择后，复述需求 + 风险提示（见文末注意事项），用户点头后再执行。
3. 提交后立刻把 task_id 给用户，并说明预计等待时长（5~15s 视频通常 40~80s 出片）。

AskUserQuestion 卡片示例（以「小狗看书」为例）

第 1 轮：时长

• header: 时长
• question: 「小狗看书」本次走【文生视频 t2va】，时长想要多长？
• options:
  • 5 秒（短平快）
  • 6 秒（通用默认）
  • 10 秒（一个完整动作段落）
  • 15 秒（最长）

第 2 轮：画面比例

• header: 画面比例
• question: 「小狗看书」本次走【文生视频 t2va】+ 6 秒，画面比例选哪个？
• options:
  • 16:9 横屏（最通用）
  • 9:16 竖屏（短视频平台）
  • 1:1 方屏（社群分享）
  • 21:9 宽幅（电影感）

第 3 轮：分辨率

• header: 分辨率
• question: 「小狗看书」本次走【文生视频 t2va】+ 6 秒 + 16:9 横屏，分辨率选哪个？
• options:
  • 2K（最高画质，仅 MiniMax-H3 支持）
  • 768P（通用，两个模型都支持）
  • 480P（仅 MiniMax-H3-Max 支持）

第 4 轮：水印（非必填，可跳过）

• header: AIGC 水印
• question: 「小狗看书」本次走【文生视频 t2va】+ 6 秒 + 16:9 横屏 + 2K，是否需要 AIGC 水印？
• options:
  • 不加水印（默认行为）
  • 加 AIGC 水印（需要显式传参才会添加）
• 跳过则取默认 不加水印

配套脚本

选项定义集中在 options.json，改参数只改这一个文件，不用动脚本：

python scripts/interactive.py --spec     # 查看本模型所有可选项与合法取值（JSON）
python scripts/interactive.py            # 终端里一步步选，最后给出可直接执行的命令
python scripts/interactive.py --prompt "..." --answers "duration=6,ratio=9:16"   # 非交互拼命令

Prompt 写作规范（官方结构化格式，强烈建议遵守）

用户给的往往是一句中文口语（"一只猫在月光下弹钢琴"），不要原样丢进去。按 MiniMax 官方 h3-prompt-writing 规范，把需求改写为结构化字段的英文 prompt：

硬性要求：

• 正文用英文；只有台词/歌词/画面可见文字保留原文语言。
• I2VA / FL2VA / L2VA 必须在 prompt 首行写关键帧对齐指令（如

For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.），后接一个空行。

• 首个镜头写 [Shot 1] 不加时间戳；后续 [Shot 2] At 00:03.000, ...，时间戳严格递增且在时长内。
• 运镜写成句子里的动作：运动类型 + 幅度 + 速度（The camera pushes in with small amplitude at slow speed toward ...）。
• 说话人用 (S1) 稳定 ID，台词写 <d>[English] ...</d>，原话逐字保留。
• overall_soundscape 只写环境音/物理音/非语言人声；non_diegetic_music 只写观众专属配乐，都不重复台词；没有就写 N/A。
• Ref2VA 用 <Subject N> / <Picture N> / <Video N> / <Audio N> 标签，

retention_analysis 逐标签标注 fully_preserved / partially_preserved / attribute_transfer / weak_reference（音频用 fully_copy / partially_copy / reference / weak_reference）。

• 描述总时长必须与请求时长（4~15 秒）匹配；优先具体视听细节，少用 cinematic、beautiful 这类抽象词。

长 prompt 一律写进文件再用 --prompt-file 提交，避免 Windows 命令行长度限制和引号转义：

python scripts/create_video.py --prompt-file D:/tmp/prompt.txt --duration 10 --resolution 768P

速查：references/h3-prompt-writing.md（规范摘要）

原文存档：references/official/h3-prompt-writing-full.md

官方仓库：https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing

工作流

创建视频

文生视频（最简）：

python scripts/create_video.py --prompt "一座由硬纸板搭建的微型城市，在夜晚焕发生机"

可选：--duration <4~15>、--resolution <768P|2K>、--ratio <16:9|9:16|...>、--aigc-watermark、--model <MiniMax-H3|MiniMax-H3-Max>、--api-key <KEY>。

首帧图生视频：

python scripts/create_video.py 
  --prompt "角色慢慢转身微笑" 
  --image-url first_frame:https://example.com/first.png

单张图省略 role 时按 first_frame 处理。

图生视频（首尾帧）：

python scripts/create_video.py 
  --prompt "角色慢慢转身微笑" 
  --image-url first_frame:https://example.com/a.png 
  --image-url last_frame:https://example.com/b.png

多模态参考生视频（仅 H3）：

python scripts/create_video.py 
  --prompt "角色说：随风而行，自由自在" 
  --image-url reference_image:https://example.com/char.png 
  --video-url reference_video:https://example.com/ref.mp4 
  --audio-url reference_audio:https://example.com/ref.mp3

附加参数：--aigc-watermark（加 AIGC 水印）、--callback-url <URL>（任务完成回调；官方会先发 challenge 验证）。

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

本地图片（没有公网 URL 时）

--image-url / --image-file 都接受本地图片路径，脚本会自动读文件转 Base64 data: URI 内联上传：

python scripts/create_video.py 
  --prompt "[Image 1]中的女性在花园中漫步" 
  --image-file reference_image=D:/pic/girl.jpg 
  --image-file reference_image=D:/pic/garden.jpg 
  --ratio 9:16

• 任何模式下裸传路径也行（--image-file D:/pic/a.jpg），i2va 按 first_frame 处理、r2va 按 reference_image 处理。
• Windows 路径含 : 没问题（脚本只在 type= / type: 前缀处切分，C: 不会被误判）。
• 单图上限 30 MB（与官方一致），超限脚本直接报错；请求体总大小仍是 64 MB，图片多就先压缩。
• 不要手动把 Base64 拼到命令行上——Windows 命令行有长度上限，会截断。交给脚本从文件读。

参考视频（用户说"参考这个视频生成"时）

MiniMax-H3 接受视频文件（与 HappyHorse 不同），官方约束：

• MP4 / MOV，H.264/AVC 或 H.265/HEVC（音频 AAC、MP3）
• 单文件 ≤ 50 MB
• 段数 ≤ 3，单段 [2, 15] s，总时长 ≤ 15 s
• 宽高 [256, 5760] px，长宽比 [0.4, 2.5]
• 帧率 [23.976, 60]

如果参考视频不满足上述约束（如片段太长），需要用 ffmpeg 先切：

<ffmpeg> -ss 0 -t 10 -i input.mp4 -vf "scale=-2:720" -c:v libx264 -c:a aac ref_clip.mp4

查询状态（按 ID）

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

打印当前 status、成片 URL、progress、created_at / updated_at、usage 等；可加 --raw 看原始 JSON。

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

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

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

取消任务

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

实测结论：取消接口正确路径是 DELETE /v1/videos/{task_id}（注意 videos 复数），不是创建/查询用的 /v1/video/generations/{task_id}（对后者发 DELETE 会报 400）。config.json 的 endpoints.cancel 已修正为 /v1/videos/{task_id}。

只能取消还在排队中（queued）的任务；running 后取消可能失败，任务仍会跑完。

模型差异

切换：加 --model MiniMax-H3-Max；脚本会根据模型自动校验分辨率/时长/参考素材的合法性。

使用注意

• 用哪个 Python 均可（脚本仅依赖标准库 urllib），若有托管 Python 优先用它。
• 拿到成片视频地址后按用户需要告知、下载到本地，或直接展示。链接限时 24 小时，需及时转存。
• 禁止用对话模型"看"成片：很多对话模型没有视觉能力，被要求看视频/图片时会编造"我看了，没问题"这类结论。成片一律交由用户自己判断；客观信息（时长、体积、是否损坏）用命令读取，不要用模型看。
• 请求体总大小 ≤ 64 MB；大文件用公网 URL，避免 Base64。
• prompt：≤7000 字符（图生也必填，因为官方强制每请求必含一个非空 text）。
• duration 整数；H3: 4~15 / H3-Max: 5~15；resolution 仅 768P / 2K（H3）或 480P / 768P（H3-Max）；ratio 仅 adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16，且 t2va 必填且不能 adaptive。
• i2va 模式 ratio 由首帧图自适应，传其它值会被忽略；r2va 模式 ratio 默认 adaptive。
• AIGC 水印默认不加，加 --aigc-watermark 开启。
• 接口场景约束、media 取值、错误码、完整 curl 示例见 references/api.md。

错误码

错误响应结构：

{ "error": { "code": "...", "message": "..." } }

脚本清单

• scripts/common.py 配置加载、鉴权、HTTP、响应归一化、模型 profile
• scripts/create_video.py 创建任务（含 --check-key / --save-key / --image-file 本地图片上传 / --prompt-file 读长 prompt）
• scripts/query_video.py 查询任务状态
• scripts/wait_video.py 自动轮询等待任务完成
• scripts/cancel_video.py 取消 / 删除任务
• scripts/interactive.py 交互式选项向导（终端）
• options.json 选项定义（修改参数只动这里）

参考文档

• references/h3-prompt-writing.md 官方 prompt 写作规范摘要（字段结构 / 镜头 / 运镜 / 标签 / 标记）
• references/official/h3-prompt-writing-full.md 官方三份指南原文存档（SKILL.md + base-en + ref-en）
• references/api.md 完整接口规格、参数约束、错误码、模型差异表
• 官方 API 文档：https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create
• 官方 prompt skill：https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing