FAQ:wan / happyhorse 视频生成常见问题

看 README.md 跑通基础流程,看这里解决具体疑问。

A. 入门 / 鉴权

A1. 我没有 key,怎么拿?

到 apiyi.com 注册账户、充值,后台会生成一串 sk- 开头的 API key。这串 key 同时具备调用本文所有视频模型的权限,不需要为每个模型单独申请。

A2. 我需要阿里云账号吗?

不需要。apiyi 是中转站,它替你跟阿里云 DashScope 对接、按用量结算给你。你只跟 apiyi 一家打交道。

A3. 一个 key 能并发跑几个任务?

实测可以同时提交 4-8 个任务并不报限流,但不要无限并发。生产建议:同时活跃任务 ≤ 10 个,超出就排队。

B. 端点 / 协议

B1. 为什么文档里说”不要用 `/v1/videos`”?

apiyi 同时挂着两条路径:

/v1/videos —— OpenAI 风格扁平 schema,对 wan2.7 的 i2v / r2v 适配不完整(媒体字段会被丢弃)
/wan/api/v1/services/aigc/video-generation/video-synthesis —— 真正的 DashScope 透传,所有模型完整可用

直接用第二条,别看到 /v1/videos 就上。

B2. `X-DashScope-Async: enable` 这个头是干啥的?

告诉中转站”这是个异步任务,立刻返回 task_id 不要堵塞等结果”。不带这个头会被拒。所有创建请求都要带。

B3. 查任务为什么是 `/v1/tasks/{id}` 而不是 `/wan/api/v1/tasks/{id}`?

apiyi 把所有视频任务的查询端点统一收口到了 /v1/tasks/{id}。不管你用哪个路径创建的,查任务都走这一个端点。

B4. 创建任务返回的 `request_id` 有什么用?

apiyi 内部追踪用,如果要找 apiyi 客服排查问题,把这个 request_id 给他们,定位很快。普通调用流程里不需要用它。

C. 请求体 / 字段

C1. `prompt` 应该放顶层还是 `input` 里?

放 input.prompt 里,不要放顶层。这是 DashScope 原生约定。如果你看到顶层 prompt 的 demo,那是另一条 /v1/videos 路径的写法,那条对视频模型不可用。

C2. `resolution` 写 `720p` 还是 `720P`?

写大写 720P。小写有时能通,大写更稳。同样:480P / 1080P。

C3. `duration` 传字符串还是数字?

整数。"duration": 5,不是 "duration": "5"。传字符串会报 cannot unmarshal string into Go struct field ... of type int。

C4. `prompt_extend` 是啥?要不要开?

模型自动扩写你的 prompt,加细节让画质提升。强烈推荐 true,本项目所有验证用例都开了。代价就是稍微多几秒生成时间。

C5. `watermark: true` 真的会加水印?

会。完成的视频右下角会有”AI 生成”水印。商用建议开,避免被误传播;研发调试关掉看效果更好。

C6. media 类型一共有几种?

实测可用:

first_frame —— 首帧图(i2v 用)
last_frame —— 尾帧图(部分模型支持,本项目未单独验证)
reference_image —— 参考图(r2v / video-edit 用,可多张)
driving_audio —— 驱动音频(只有 wan2.7-i2v 支持)
video —— 输入视频(video-edit 用)

C7. 同一个 `media` 数组里可以混不同 type 吗?

可以。wan2.7-i2v 就是 first_frame + driving_audio 混传;video-edit 是 video + reference_image 混传。

C8. 我可以塞 9 张 reference_image 吗?

happyhorse-1.0-r2v 官方说最多 9 张,直接放在 media 数组里就行:

"media": [
  {"type": "reference_image", "url": "https://..."},
  {"type": "reference_image", "url": "https://..."},
  ...
]

C9. 媒体 URL 一定要公网可达吗?本地图怎么办?

必须公网可达。本地图请先上传到任意公开 OSS / CDN(七牛、阿里云 OSS、imgur 都行),拿到 https URL 再传给 API。私网图、需要鉴权才能拿的图,上游下载失败任务会 failed。

D. 轮询 / 下载

D1. 多久查一次状态合适?

5-10 秒一次。本项目客户端默认 10 秒。不要小于 3 秒,会被限流。

D2. 状态值有哪些?各代表什么?

状态	含义	下一步
`submitted`	已提交,排队中	等
`in_progress`	生成中	等(常见会卡在 30% 一段时间,这是阿里云上游汇报频率低,不是 bug)
`completed`	成功	从 `result_url` 下载
`failed`	失败	看 `error.message` 或 `fail_reason`

D3. 为什么 progress 一直停在 30%?

阿里云上游汇报的 progress 是粗粒度的(只有 0% / 10% / 30% / 100% 几档),不是真的卡住。只要 status 还是 in_progress 就继续等,通常 30% 到 100% 之间是直接跳过的。

D4. 一般要等多久?

模型	5s @720P 中位耗时
`wan2.7-t2v`	100-120s
`wan2.7-i2v`	70-90s
`wan2.7-r2v`	120-140s
`wan2.7-videoedit`	视输入视频长度而定,本项目实测 ~100s
`happyhorse-1.0-*`	105-115s

1080P / 10 秒以上视频会显著更慢,建议把超时设到 20 分钟。

D5. `result_url` 下载报 403 / SignatureDoesNotMatch?

Authorization 头。result_url 已经是 OSS 签好的链接,再带你的 apiyi key OSS 反而会拒。

# ✅ 对
curl -L -o out.mp4 "$RESULT_URL"

# ❌ 错
curl -L -H "Authorization: Bearer $KEY" -o out.mp4 "$RESULT_URL"

D6. `result_url` 过期了怎么办?

链接有效期默认 24 小时。过期后重新 GET 任务详情(/v1/tasks/{id})会得到一个新的 result_url。但任务详情本身保留时间也有限(具体看 apiyi 政策),需要长期存视频请尽快下载到自己的存储。

D7. 任务详情里的 `result.data.input` 和 `properties.input` 有什么区别?

用 /wan/api/v1/... 端点(DashScope 透传)创建的任务 → 看 result.data.input / result.data.parameters
用 /v1/videos 端点(OpenAI 风格)创建的任务 → 看 properties.input / properties.submit / properties.ratios

两种创建方式下任务详情的内部结构不同,但顶层的 status / progress / result_url / error 字段一致,所以应用层判断结果时只看顶层就够了。

E. 错误码索引

E1. `{"message":"prompt is required",...}` (HTTP 4xx)

你 prompt 放在了顶层。改成 input.prompt 即可,见 §C1。或者你用错了端点 —— 必须用 /wan/api/v1/...,不是 /v1/videos。

E2. `{"message":"图生视频模型 ... 必须提供图片","code":"build_request_failed"}` (HTTP 500)

你调的是 i2v / r2v 模型但没传 input.media,或传到了错误的字段名。检查 body 是否符合 §4 示例。

E3. `{"message":"解析请求失败: json: cannot unmarshal ...","code":"parse_request_failed"}` (HTTP 400)

字段类型错。常见:

duration 应该是 int,你传了 string
seed 应该是 int,你传了 string
prompt_extend / watermark 应该是 bool,你传了 string

E4. `{"error":{"message":"当前分组 ... 无可用渠道",...}}` (HTTP 503)

这个 key 没开通你请求的模型,或者模型名拼错了。例如 wan2.7-image-pro 是图片模型不是视频模型(走 /v1/images/generations),走视频端点就会被拒。

E5. 任务 `failed` + `"[InvalidParameter] Field required: input.media"`

apiyi 没把媒体字段转发给上游。100% 是用了 /v1/videos 错端点,改用 /wan/api/v1/...。

E6. 任务 `failed` + `"[InvalidImageUrl]"` / `"图片下载失败"`

媒体 URL 不可达 / 需要鉴权 / 太大。换成公网直链。

E7. 任务 `failed` + `"[InvalidParameter] prompt 含敏感内容"`

prompt 涉敏。改 prompt;或者你在做合规相关业务,可能需要联系阿里云开白。

E8. HTTP 504 / 网络超时

中转或上游临时抖动。等 30 秒后整体重新创建任务(不要直接重试同一个 task_id 的查询)。

F. 计费

F1. 怎么算钱?

公式大约是:单价 × 时长 × 分辨率倍率 × 用户折扣。任务详情里的 properties.ratios(走 /v1/videos 端点创建的)或 apiyi 后台账单页面会有精确扣费。

F2. 失败的任务扣费吗?

status=failed 不扣。但需要注意:任务在上游已经开始执行后失败(比如生成到一半失败)有可能扣费,具体看 apiyi 政策。建议在测试期把 prompt_extend 关掉降低单价。

F3. 怎么避免误扣?

别用合法 model + prompt 做 schema 试探(我之前犯过这个错):字段名不被 apiyi 识别时它会静默忽略直接创建任务。试探时用假 model 名让它在第一步就报错。
上线前用 wan2.6-t2v-flash / 短 prompt / 480P / 5s 这种最低组合开发联调,稳定后再切到正式参数。

G. happyhorse vs wan2.7 差异

G1. happyhorse 比 wan2.7 优势是什么?

happyhorse-r2v 官方支持 9 张参考图(wan2.7-r2v 张数限制需要查上游文档)
happyhorse-video-edit 官方支持 5 张参考图局部/全局编辑
模型整体偏”高度还原动态画面”风格,人物/物体保持得更稳

劣势:happyhorse-i2v 不支持 driving_audio,做对口型/rap 必须用 wan2.7-i2v。

G2. 接入有差别吗?

没有。所有 8 个已验证模型(wan2.7-2v + videoedit、happyhorse-1.0-2v + video-edit)共用同一个端点、同一套 schema、同一组 media type 名,只改 model 字段即可切换。

G3. wan2.6 系列还能用吗?

apiyi 文档里 wan2.6-t2v / i2v / r2v / r2v-flash 都还在测试模型列表里。协议同 wan2.7,本项目没单独跑过,但只改 model 名应该可用。

H. 生产接入

H1. 推荐的并发模型怎么做?

提交 / 轮询解耦:提交时立刻返回 task_id 给业务,轮询走独立 worker
用 Redis / 数据库存 task_id 状态,worker 每 10 秒批量查所有 in_progress 任务
result_url 拿到后立即下载到自己的 OSS 长存

H2. 怎么做幂等?

业务层维护”业务 ID → task_id”映射。同一业务 ID 不重复提交:

def get_or_create(biz_id, body):
    if cached := redis.get(f"task:{biz_id}"):
        return cached
    task_id = wan_create(body)
    redis.setex(f"task:{biz_id}", 24*3600, task_id)
    return task_id

H3. 错误重试怎么写?

HTTP 5xx / 网络错误 → 指数退避重试 3 次(1s / 4s / 16s)
HTTP 4xx → 立刻 surface 报错,不要重试(重试也是同样错)
任务 failed 含 [InvalidImageUrl] → 可以重试(可能是临时网络)
任务 failed 含 [InvalidParameter] / 敏感词 → 不重试

H4. 监控指标建议

create_latency_ms(p50 / p99)
task_total_latency_ms(p50 / p99,分模型)
create_error_rate(创建失败率)
task_fail_rate(执行失败率)
download_success_rate(完成后下载成功率)

H5. 怎么做安全的 key 管理?

key 别 commit 进 git,用环境变量或 secret manager
后端代理调用,永远不要把 key 暴露给前端
不同业务用不同 key,挂掉一个不影响别的
定期轮换:apiyi 后台可以多发几个 key 互相兜底

Documentation Index

​FAQ:wan / happyhorse 视频生成常见问题

​A. 入门 / 鉴权

​A1. 我没有 key,怎么拿?

​A2. 我需要阿里云账号吗?

​A3. 一个 key 能并发跑几个任务?

​B. 端点 / 协议

​B1. 为什么文档里说”不要用 /v1/videos”?

​B2. X-DashScope-Async: enable 这个头是干啥的?

​B3. 查任务为什么是 /v1/tasks/{id} 而不是 /wan/api/v1/tasks/{id}?

​B4. 创建任务返回的 request_id 有什么用?

​C. 请求体 / 字段

​C1. prompt 应该放顶层还是 input 里?

​C2. resolution 写 720p 还是 720P?

​C3. duration 传字符串还是数字?

​C4. prompt_extend 是啥?要不要开?

​C5. watermark: true 真的会加水印?

​C6. media 类型一共有几种?

​C7. 同一个 media 数组里可以混不同 type 吗?

​C8. 我可以塞 9 张 reference_image 吗?

​C9. 媒体 URL 一定要公网可达吗?本地图怎么办?

​D. 轮询 / 下载

​D1. 多久查一次状态合适?

​D2. 状态值有哪些?各代表什么?

​D3. 为什么 progress 一直停在 30%?

​D4. 一般要等多久?

​D5. result_url 下载报 403 / SignatureDoesNotMatch?

​D6. result_url 过期了怎么办?

​D7. 任务详情里的 result.data.input 和 properties.input 有什么区别?

​E. 错误码索引

​E1. {"message":"prompt is required",...} (HTTP 4xx)

​E2. {"message":"图生视频模型 ... 必须提供图片","code":"build_request_failed"} (HTTP 500)

​E3. {"message":"解析请求失败: json: cannot unmarshal ...","code":"parse_request_failed"} (HTTP 400)

​E4. {"error":{"message":"当前分组 ... 无可用渠道",...}} (HTTP 503)

​E5. 任务 failed + "[InvalidParameter] Field required: input.media"

​E6. 任务 failed + "[InvalidImageUrl]" / "图片下载失败"

​E7. 任务 failed + "[InvalidParameter] prompt 含敏感内容"

​E8. HTTP 504 / 网络超时

​F. 计费

​F1. 怎么算钱?

​F2. 失败的任务扣费吗?

​F3. 怎么避免误扣?

​G. happyhorse vs wan2.7 差异

​G1. happyhorse 比 wan2.7 优势是什么?

​G2. 接入有差别吗?

​G3. wan2.6 系列还能用吗?

​H. 生产接入

​H1. 推荐的并发模型怎么做?

​H2. 怎么做幂等?

​H3. 错误重试怎么写?

​H4. 监控指标建议

​H5. 怎么做安全的 key 管理?