zhishu-happyhorse

概述

Zhishuai HappyHorse 视频生成

连接用户自己的视频生成服务（https://www.zhishuai.net，默认模型 happyhorse-1.1-t2v）。完整支持三种内容模式（通过 model 名后缀路由），所有模式互斥。

何时使用

• 用户要求"用 happyhorse / HappyHorse / HH 生成视频"。
• 用户描述"按这张图做视频""以这张图为参考出视频""参考这个角色生成"。
• 用户提供 task_id（形如 task_xxx）要求"查状态""等它完""取消它"。
• 注意：与 MiniMax-H3 / Seedance 2.5 分属不同 skill；路径/请求结构/状态枚举都不同；

若用户提到 H3 / Seedance 请引导其使用对应的 zhishuai-h3 / zhishuai-seedance skill。

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

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

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

用一条无副作用命令判断是否需要配置（不联网、不发请求）：

BASH复制

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

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

即使用户没提"首次使用"，只要 --check-key 返回 UNSET，就必须先要 Key 再继续；

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

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

1. 问画面描述：用户没给清楚就先问一句（自由文本）。
2. 弹选项卡片让用户点选：用 AskUserQuestion 一次性问 4 项，选项直接取自 options.json：

生成模式 → 时长 → 画面比例 → 分辨率。水印 / 音频 / 附加选项等次要项，用户没提就按 options.json 里的 default 走，不必挨个问。

1. 复述需求 + 风险提示（见文末注意事项），用户点头后再执行。
2. 提交后立刻把 task_id 给用户，并说明预计等待时长。

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

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

首次使用：交互配置 API Key（重要）

发布版的 config.json 里 api_key 是占位符 YOUR_API_KEY_HERE，首次使用前必须配置，否则请求会返回 401。本技能支持两种配置方式，优先走「对话输入框」。

方式 A — 弹输入框卡片（agent 标准动作，推荐）：当且仅当「强制第 0 步」的 --check-key 返回 UNSET 时执行。必须用 AskUserQuestion 弹出一个带输入框的卡片（不是普通聊天提问），让用户直接在输入框里粘贴 Key：

1. 调用 AskUserQuestion，参数示例：
   • header: 配置Key
   • question: 「检测到 zhishuai-happyhorse 尚未配置 API Key（首次使用）。请在下方输入框粘贴你的 www.zhishuai.net API Key（以 sk- 开头），我会写入本地配置并继续生成：」
   • options（2 项）：我已在输入框填入 Key（说明：把 Key 贴在卡片底部的「其他」输入框，再选这项提交） / 暂不配置，取消本次生成。
2. 用户把 Key 填进输入框（走「其他」自由文本）后，agent 取到文本，先校验以 sk- 开头；不符合则再次弹框要求重填，不要写入。
3. 执行一次性保存命令（把 Key 写入 config.json）：

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

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

1. 提示用户「配置已保存，现在可以直接生成了」，然后回到「强制第 0 步」重新 --check-key 应得 OK，再继续标准生成流程（同一次对话内无缝衔接，不用用户重复操作）。

方式 B — 终端配置（无 agent 时）：在终端运行

python scripts/interactive.py --configure-key

按提示输入 Key，自动写入 config.json。

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

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

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

配置文件路径：<skill 目录>/config.json，即~/.workbuddy/skills/zhishu-happyhorse__skillhub/config.json（注意目录名是 zhishu-happyhorse__skillhub，不是 zhishuai-happyhorse；endpoints.cancel 必须是 /v1/videos/{task_id}，见「取消任务」）。

模型与场景

脚本根据 --model 自动推导场景并校验 media 与 prompt 的合法性，无需额外指定。

工作流

创建视频

文生视频（最简）：

python <skill>/scripts/create_video.py 
  --model happyhorse-1.1-t2v 
  --prompt "一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发生机"

可选：--duration <3~15>、--resolution <720P|1080P>、--ratio <16:9|...>、--no-watermark、--seed <int>、--api-key <KEY>。

首帧图生视频：

python <skill>/scripts/create_video.py 
  --model happyhorse-1.1-i2v 
  --prompt "一只猫在草地上奔跑" 
  --image-url first_frame=https://example.com/cat.jpg

i2v 模式下 prompt 可省略；比例按首帧图自动确定，不可指定 ratio。

参考生视频（1~9 张参考图 + prompt 中用 [Image 1]、[Image 2] 占位）：

python <skill>/scripts/create_video.py 
  --model happyhorse-1.1-r2v 
  --prompt "[Image 1]中的女性在花园中漫步，微风吹起她的裙摆" 
  --image-url reference_image=https://example.com/girl.jpg 
  --ratio 16:9

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

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

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

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

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

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

HappyHorse 的 media 只收图片，不接受视频文件。所以正确做法是「先抽帧，再走 i2v / r2v」：

1. 抽帧需要 ffmpeg。本机通常没有，装一个自带二进制的 Python 包即可（约 30 MB）：

   <venv>/Scripts/pip.exe install imageio-ffmpeg -i https://pypi.tuna.tsinghua.edu.cn/simple

直接装官方源可能十几分钟不动，务必加国内源。拿到可执行文件路径：python -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())"

1. 按时间点抽关键帧（3~5 张就够，多了意义不大）：

   "$FF" -ss 0.4 -i input.mp4 -frames:v 1 -q:v 2 -y ref_frame_1.jpg

1. 用 --image-file 把抽出的帧当参考图提交（r2v 用 [Image N] 占位）。

参考图要求短边 ≥ 400px，抽 1080P 素材的帧天然满足。

查询状态（按 ID）

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

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

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

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

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

取消任务

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

实测结论（2026-09-09）：取消接口正确路径是 DELETE /v1/videos/{task_id}，不是创建/查询用的/v1/video/generations/{task_id}（对后者发 DELETE 会报 400 未指定模型名称，说明路由不存在）。config.json 的 endpoints.cancel 已修正为 /v1/videos/{task_id}。

但该平台实际不支持取消：即使路径正确，服务端仍返回

HTTP 501：platform 17 does not support task cancellation

所以用户要求取消时，直接告知「HappyHorse 平台不支持取消任务，任务会继续跑完并计费」，不要反复重试或改路径。任务不存在时该接口返回 400 {"code":"task_not_exist"}。

使用注意

• 用哪个 Python 均可（脚本仅依赖标准库 urllib），若有托管 Python 优先用它。
• 拿到成片视频地址后按用户需要告知、下载到本地，或直接展示。链接限时 24 小时，需及时转存。
• 禁止用对话模型"看"成片：很多对话模型没有视觉能力，被要求看视频/图片时会编造"我看了，没问题"这类结论。成片一律交由用户自己判断；客观信息（时长、体积、是否损坏）用命令读取，不要用模型看。
• 请求体总大小 ≤ 64 MB；大文件用公网 URL，避免 Base64。
• prompt：中文 ≤2500 字 / 非中文 ≤5000 字符（图生可选，其余必填）。
• duration 整数 3~15；resolution 仅 720P/1080P（大写 P）；ratio 仅 16:9/9:16/1:1/4:3/3:4/4:5/5:4/9:21/21:9，且仅 t2v/r2v 支持。
• 水印默认开启（"Happy Horse"），加 --no-watermark 关闭。
• 接口场景约束、media 取值、错误码、完整 curl 示例见 references/api.md。

错误码

实测记录（2026-09-09，全部接口跑通）

响应结构（与官方文档描述不同，脚本已兼容）：

• 创建 POST /v1/video/generations → 顶层平铺：

{id, task_id, object, model, status:"queued", progress:0, created_at}，id 与 task_id 相同。

• 查询 GET /v1/video/generations/{task_id} → 包一层 {code, message, data:{...}}，

其中 data.id 是数字（如 50647），真正的任务号在 data.task_id（task_xxx）。

• 成片地址在 data.result_url，同时在 data.data.output.video_url；

data.data.usage 里有 {SR, ratio, duration, video_count, output_video_duration}，可用来核对参数是否生效。

状态枚举（实际为大写）：NOT_START → IN_PROGRESS → SUCCESS（失败应为 FAILURE）；内层 data.data.output.task_status 另有 PENDING / RUNNING / SUCCEEDED。脚本内部统一 lower 后比较，能正确识别。

实测样例：

第 4 条的服务端回执 data.data.usage = {SR:1080, ratio:"9:16", duration:3} 与请求参数完全一致，说明 --resolution 1080P / --ratio 9:16 / --duration 3 / --no-watermark 都真实生效（无水印时成片文件名不带 _watermark 后缀，可作为一眼核对的依据）。

• 公网图片 URL（如 https://picsum.photos/...）服务端能正常拉取，i2v/r2v 均出片，无需 Base64。
• 成片 URL 带 Expires 参数，实测有效期正好 24 小时。
• 查询不存在的 task_id → 400 task_not_exist；错误 Key → 401 Invalid token。
• 本地参数校验已覆盖：duration 越界、resolution 小写、i2v 传 ratio、t2v 传图、r2v 缺图、

i2v 缺首帧图、模型后缀非法、seed 越界、ratio 非法、t2v 缺 prompt —— 全部正确拦截且不发请求。