HappyHorse 视频生成（阿里云）

阿里云 HappyHorse-1.1 视频生成系列完整指南：文生视频 / 图生视频 / 参考图生视频（≤9 张参考图）/ 视频编辑，统一 DashScope 异步端点，主体高度还原。

​

概述

HappyHorse（快马） 是阿里系视频生成模型系列，主打高度还原的动态画面生成——精准理解文本语义，输出流畅自然、细节丰富、主体保持稳定的高质量视频。API易 通过 DashScope 透传通道 直连，让你用一个 API易 Key 即可调用全部 HappyHorse 能力。当前主力版本 HappyHorse-1.1（视频编辑为 1.0）覆盖四种核心玩法：

玩法	模型 ID	你给的输入	产出
文生视频	happyhorse-1.1-t2v	一段文本 prompt	短视频
图生视频	happyhorse-1.1-i2v	首帧图 + prompt	让静态图”动起来”（不支持音频驱动）
参考图生视频	happyhorse-1.1-r2v	最多 9 张参考图 + prompt	主体与场景高度还原的视频
视频编辑	happyhorse-1.0-video-edit	视频 + 最多 5 张参考图 + 指令	局部/全局编辑后的视频

🐎 核心亮点：四种能力共用同一个异步端点和同一套请求结构，切换玩法只改 model 字段。HappyHorse 偏「高度还原动态画面」，参考图生视频支持 最多 9 张参考图、视频编辑支持 最多 5 张参考图，主体一致性强。与 Wan 系列 同端点、可直接互换。

文生视频 API

happyhorse-1.1-t2v，纯文本提示词生成视频。

图生视频 API

happyhorse-1.1-i2v，首帧图生成视频（无音频驱动）。

参考图生视频 API

happyhorse-1.1-r2v，最多 9 张参考图保持主体。

视频编辑 API

happyhorse-1.0-video-edit，最多 5 张参考图编辑视频。

​

让 AI Agent 帮你接入

复制这段提示词，粘贴给 Codex / Claude Code / Cursor

它会先抓本页的纯文本版（任意文档页地址后加 .md），再按你项目的技术栈写代码——异步轮询、不能用 /v1/videos、缺 X-DashScope-Async 头会报错、duration 必须是整数这几个高频坑已经写死在要求里。

帮我在当前项目里接入 / 排查 HappyHorse 的视频生成（文生视频 / 图生视频 / 参考生视频 / 视频编辑）。

先读文档再动手：抓 https://docs.apiyi.com/api-capabilities/happyhorse/overview.md 拿到本页纯文本版；四种能力各有一页 …

1. 端点和异步头（最容易一上来就卡住的两条）：提交必须打 …

共 10 条接入要求，点下方按钮复制完整版

已复制复制提示词

这段提示词替你挡掉了什么

要求	挡掉的坑
不能用 /v1/videos	那条路会静默丢掉 media 字段，上游报缺少 input.media，看起来像参数写错其实是端点选错
必须带 X-DashScope-Async	缺这个头会被当成同步调用直接拒绝
提交与轮询前缀不同	提交在 /wan/api/v1/...，轮询却在 /v1/tasks/{task_id}
模型名是 video-edit 带连字符	与 Wan 的 wan2.7-videoedit（无连字符）相反，两个系列一起接时最容易写错
i2v 没有 driving_audio	那是 Wan 独有的能力，照搬 Wan 的代码会白传一个无效字段
重复提交会重复计费	失败不计费，但无脑重试等于多付钱，必须自己做幂等
下载不带 Authorization	OSS 签名直链带 Auth 反而 403，且链接 24 小时过期

​

为什么选 API易 的 HappyHorse

一个 Key 调全部能力

无需注册阿里云、无需配置地域。一把 API易 Key 即可调用 HappyHorse 全部四种能力以及 Wan 系列。

国内直连 · 免出海

直连 api.apiyi.com，国内机房、家宽网络均可访问。

失败不计费

任务进入 failed 状态（媒体 URL 不可达、prompt 涉敏等）不计费，可放心重试。

DashScope 协议透传

与 Wan 系列共用同一端点和 schema，已有 Wan 代码切 model 名即可调用 HappyHorse。

​

核心特性

四合一异步端点

t2v / i2v / r2v / video-edit 共用 POST /wan/api/v1/...video-synthesis，提交后返回 task_id，轮询 + 下载。

主体高度还原

模型整体偏「高度还原动态画面」风格，人物/物体在动态过程中保持得更稳。

最多 9 张参考图

happyhorse-1.1-r2v 官方支持最多 9 张 reference_image，多参考图场景的主体一致性更强。

多档分辨率与时长

720P / 1080P 分辨率，2–15 秒整数时长，prompt_extend 智能改写提升短 prompt 画质。

​

支持的模型

模型 ID	能力	必需媒体输入	说明
happyhorse-1.1-t2v	文生视频	无	纯文本生成
happyhorse-1.1-i2v	图生视频	first_frame	不支持 driving_audio
happyhorse-1.1-r2v	参考图生视频	reference_image（最多 9 张）	多参考图主体保持
happyhorse-1.0-video-edit	视频编辑	video + reference_image（最多 5 张）	模型名 有连字符

​

分组介绍

HappyHorse 与 Wan 两个系列共用同一个 Wan&HappyHorse 分组——一把令牌即可同时调用两个系列。视频模型按秒计费，令牌必须同时满足两个条件才能成功路由：

1. 计费模式：选「按量优先」或「按量计费」—— 视频按秒计费，按次计费的令牌无法路由
2. 分组：选择包含 Wan&HappyHorse

创建令牌：计费模式选「按量优先」，分组选 Wan&HappyHorse（0.14x），即可调用 Wan2.7 与 HappyHorse 全部视频模型（截图中为分组旧名 Wan，现已更名 Wan&HappyHorse）

​

模型定价

​

默认价格 = 阿里云官方原价的 98％（理解简单）

API易 系统已内置 HappyHorse 全部模型的价格，无需任何手动配置，通过分组折扣自动生效。控制台里 Wan&HappyHorse 分组显示倍率 0.14x，这是按人民币计价单位计的。本站统一用美元充值、固定汇率 1:7，实际折算：

0.14（人民币计价单位） × 7（固定汇率） = 0.98

也就是说，默认价格 = 阿里云官方原价的 98%（98 折）——比官方直采更省，且无需自建出海链路。

换算公式：本站每秒美元价 = 官方人民币原价 × 0.14（即 × 0.98 ÷ 7）。

​

价格明细（默认价，按秒计费）

HappyHorse-1.1 文生 / 图生 / 参考生视频同价，仅 720P / 1080P 两档（不支持 480P）：

分辨率	官方原价	本站默认价/秒	5 秒	10 秒	12 秒
720P	¥0.9/秒	$0.126/秒	$0.63	$1.26	$1.51
1080P	¥1.6/秒	$0.224/秒	$1.12	$2.24	$2.69

• happyhorse-1.0-video-edit（视频编辑）输出时长跟随源视频，按实际输出秒数计费，不由 duration 决定。
• 表中为 默认价（官方 98%）；叠加充值加赠最高档约为表中价 ÷ 1.2（例：1080P 5 秒 $1.12 → 约 $0.93）。

​

叠加充值加赠，折扣进一步走低

参与 充值加赠活动 后，到账额度最高可放大约 1.2 倍，等效价格进一步下探：

0.98 ÷ 1.2 ≈ 0.816

即大客户最低可做到 官网约 81 折（0.98 ÷ 1.2 ≈ 0.816）。

档位	等效价格（对比阿里云官方原价）	算法
默认	98%（98 折）	倍率 0.14x × 固定汇率 7
叠加充值加赠（大客户最高档）	约 81.6%（约 81 折）	0.98 ÷ 1.2

• 计费维度 = 分辨率档位 × 时长（秒），失败任务不计费。
• 1:7 为固定结算汇率（不是优惠汇率），所有美元充值统一适用。
• 充值加赠的最高加赠档位与适用渠道见 充值加赠活动。最新倍率以 控制台 为准。

​

⚠️ 端点选择（最重要）

API易 同时挂载两条路径，只有 DashScope 透传端点对 HappyHorse 全部能力完整可用：

路径	协议风格	i2v / r2v 可用性	结论
/v1/videos	OpenAI 扁平风格	❌ 媒体字段会被丢弃	不要用
/wan/api/v1/services/aigc/video-generation/video-synthesis	DashScope 原生透传	✅ 完整可用	始终用这条

HappyHorse 与 Wan 共用同一个透传端点。看到任何文档/示例里写 /v1/videos 提交视频任务，直接忽略。所有创建请求都走 /wan/api/v1/...video-synthesis，查询统一走 /v1/tasks/{task_id}。

​

异步调用流程

整套流程是异步的三步：创建任务 → 轮询状态 → 下载视频。

1. 创建任务

   POST /wan/api/v1/services/aigc/video-generation/video-synthesis，请求头带 X-DashScope-Async: enable，立刻返回 task_id。

2. 轮询状态

   GET /v1/tasks/{task_id}（带 Authorization），每 5–10 秒查一次（不要小于 3 秒），直到 status 变为 completed。

3. 下载视频

   从响应的 result_url 直接 GET 下载 mp4，不要带 Authorization 头（OSS 签名直链，带 Auth 反而 403）。

​

任务状态说明

状态	含义	下一步操作
submitted	已提交，排队中	继续轮询
in_progress	生成中	继续轮询（progress 常停在 30%，是上游汇报粒度粗，不是卡住）
completed	成功	从 result_url 下载
failed	失败	看 error.message / fail_reason

​

完整 Python 客户端

import json, time, urllib.request

BASE = "https://api.apiyi.com"
KEY  = "sk-your-api-key"   # 你的 API易 Key

def post(path, body):
    h = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json",
         "X-DashScope-Async": "enable"}
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode(), headers=h, method="POST")
    return json.loads(urllib.request.urlopen(req).read())

def get(path):
    req = urllib.request.Request(BASE + path, headers={"Authorization": f"Bearer {KEY}"})
    return json.loads(urllib.request.urlopen(req).read())

# 1. 创建任务（切换玩法只改 model 和 media）
r = post("/wan/api/v1/services/aigc/video-generation/video-synthesis", {
    "model": "happyhorse-1.1-t2v",
    "input": {"prompt": "一只猫在草地上奔跑，阳光明媚，镜头跟随"},
    "parameters": {"resolution": "720P", "duration": 5, "prompt_extend": True, "watermark": True}
})
task_id = r["output"]["task_id"]
print("task_id:", task_id)

# 2. 轮询（5–10 秒一次）
while True:
    info = get(f"/v1/tasks/{task_id}")
    status = info["status"]
    print("status:", status, "progress:", info.get("progress"))
    if status == "completed":
        url = info["result_url"]
        break
    if status == "failed":
        raise RuntimeError(info.get("error") or info.get("fail_reason"))
    time.sleep(10)

# 3. 下载（不要带 Authorization！result_url 是 OSS 签名直链）
urllib.request.urlretrieve(url, "out.mp4")
print("saved out.mp4")

​

关键参数详解

提交时 body 为 DashScope 嵌套结构：{ model, input: { prompt, media[] }, parameters: {...} }。

​

media[] 类型

type	用途	适用模型
first_frame	首帧图（≤1 张）	i2v、r2v
reference_image	参考图（r2v 最多 9 张，video-edit 最多 5 张）	r2v、video-edit
video	输入视频	video-edit

HappyHorse 的 i2v 不支持 driving_audio（音频驱动是 Wan2.7-i2v 的专属能力）。做对口型 / rap 请用 Wan2.7。

​

parameters 字段

字段	类型	取值	说明
resolution	string	720P / 1080P	大写，建议显式指定
duration	int	2–15	秒数（整数），常用 5 / 10
prompt_extend	bool	true / false	智能改写 prompt，强烈推荐 true
watermark	bool	true / false	右下角「AI 生成」水印
seed	int	0–2147483647	固定可提升可复现性

duration 必须是 整数 5 而不是字符串 "5"；resolution 写 大写 720P 更稳。

​

如何选择 HappyHorse 还是 Wan

HappyHorse 和 Wan 都是阿里系视频模型、共用同一端点和 schema（只改 model 名即可互换），侧重不同：

维度	HappyHorse-1.1	Wan2.7
音频驱动对口型（i2v）	❌ 不支持，i2v 仅首帧	✅ wan2.7-i2v 支持 driving_audio
参考图生视频上限	参考图最多 9 张	参考图 + 参考视频合计 ≤5
视频编辑参考图	≤5 张	≤5 张
风格侧重	高度还原动态画面，主体保持稳	多主体互动、音色参考

需要多张参考图保持主体一致 → 选 happyhorse-1.1-r2v（最多 9 张）。 需要对口型 / rap / 数字人口播 → 选 Wan2.7-i2v（唯一支持音频驱动）。

​

最佳实践

1. 先用 720P / 5 秒联调

   开发期用低分辨率短视频快速验证 prompt 与参考图效果，定型后再放大分辨率与时长。

2. 始终开 prompt_extend

   prompt_extend: true 对短 prompt 的画质提升明显。

3. 轮询 5–10 秒一次

   不要小于 3 秒（会被限流）。HappyHorse 各能力 720P / 5 秒典型耗时 105–115 秒。

4. 客户端超时设 20 分钟兜底

   1080P 或长视频显著更慢，给轮询循环设置 20 分钟兜底超时。

5. 拿到 result_url 立即下载落地

   result_url 默认 24 小时过期，且是 OSS 签名直链，下载时不要带 Authorization 头。

​

错误码与重试

来源	特征	处理
创建阶段（API易 拒）	HTTP 4xx/5xx，type 为 task_error / parse_request_failed / build_request_failed	改 body 重试（字段类型错、缺 media、用错端点）
执行阶段（上游阿里云拒）	任务 status=failed，error.message 以 [InvalidParameter] / [InvalidImageUrl] 等方括号前缀打头	看方括号提示，多为媒体 URL 不可达或 prompt 涉敏

建议客户端：HTTP 5xx / 网络错误做指数退避重试；HTTP 4xx 立刻 surface 不重试；任务 failed 含 [InvalidImageUrl] 可重试，含 [InvalidParameter] / 敏感词不重试。

​

常见问题

HappyHorse 和 Wan 接入有差别吗？

没有。两者共用同一个 DashScope 透传端点、同一套请求结构、同一组 media type 名、同一个查询端点。切换只改 model 字段（如 wan2.7-t2v → happyhorse-1.1-t2v），body 其余部分一字不改。

HappyHorse 的 i2v 为什么不能做对口型？

happyhorse-1.1-i2v 不支持 driving_audio（音频驱动）字段，i2v 只接受 first_frame。做对口型 / rap / 数字人口播请用 Wan2.7-i2v。

happyhorse-1.1-r2v 真的能塞 9 张参考图吗？

可以。官方说最多 9 张 reference_image，直接放在 media 数组里即可。多参考图能让主体/服装/场景一致性更强。

为什么不能用 /v1/videos 提交？

/v1/videos 对 i2v / r2v 的 media 字段适配不完整，会导致上游报 [InvalidParameter] Field required: input.media。所有创建请求都走 /wan/api/v1/services/aigc/video-generation/video-synthesis，查询走 /v1/tasks/{task_id}。

result_url 下载报 403 怎么办？

去掉 Authorization 头。result_url 已是 OSS 签好名的直链，再带 API易 Key 反而被 OSS 拒。result_url 默认 24 小时过期，请尽快下载落地。

失败任务扣费吗？

status=failed 不扣费。但重复提交相同任务会重复计费，做好幂等。

​

相关文档

文生视频 Playground

happyhorse-1.1-t2v 在线调试

图生视频 Playground

happyhorse-1.1-i2v 首帧生成

参考图生视频 Playground

happyhorse-1.1-r2v 最多 9 张参考图

视频编辑 Playground

happyhorse-1.0-video-edit 换装 / 换背景

Wan 系列

同为阿里系，选型对照

HappyHorse 系列通过 API易 DashScope 透传通道提供。如有问题或建议，欢迎在 API易控制台 工单中反馈。