跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt

Use this file to discover all available pages before exploring further.

概述

HappyHorse(快马) 是阿里系视频生成模型系列,主打高度还原的动态画面生成——精准理解文本语义,输出流畅自然、细节丰富、主体保持稳定的高质量视频。API易 通过 DashScope 透传通道 直连,让你用一个 API易 Key 即可调用全部 HappyHorse 能力。当前版本 HappyHorse-1.0 覆盖四种核心玩法:
玩法模型 ID你给的输入产出
文生视频happyhorse-1.0-t2v一段文本 prompt短视频
图生视频happyhorse-1.0-i2v首帧图 + prompt让静态图”动起来”(不支持音频驱动
参考图生视频happyhorse-1.0-r2v最多 9 张参考图 + prompt主体与场景高度还原的视频
视频编辑happyhorse-1.0-video-edit视频 + 最多 5 张参考图 + 指令局部/全局编辑后的视频
🐎 核心亮点:四种能力共用同一个异步端点和同一套请求结构,切换玩法只改 model 字段。HappyHorse 偏「高度还原动态画面」,参考图生视频支持 最多 9 张参考图、视频编辑支持 最多 5 张参考图,主体一致性强。与 Wan 系列 同端点、可直接互换。

文生视频 API

happyhorse-1.0-t2v,纯文本提示词生成视频。

图生视频 API

happyhorse-1.0-i2v,首帧图生成视频(无音频驱动)。

参考图生视频 API

happyhorse-1.0-r2v,最多 9 张参考图保持主体。

视频编辑 API

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

为什么选 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.0-r2v 官方支持最多 9 张 reference_image,多参考图场景的主体一致性更强。

多档分辨率与时长

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

支持的模型

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

分组介绍

HappyHorse 与 Wan 两个系列共用同一个 Wan 分组——一把令牌即可同时调用两个系列(如图令牌名 Wan2.7&HappyHorse)。视频模型按计费,令牌必须同时满足两个条件才能成功路由:
  1. 计费模式:选「按量优先」或「按量计费」—— 视频按秒计费,按次计费的令牌无法路由
  2. 分组:选择包含 Wan
创建令牌界面:计费模式选「按量优先」,分组下拉中选择 Wan(倍率 0.14x),令牌可同时用于 Wan2.7 与 HappyHorse

模型定价

默认价格 = 阿里云官方原价的 98%(理解简单)

控制台里 Wan 分组显示倍率 0.14x,这是按人民币计价单位计的。本站统一用美元充值、固定汇率 1:7,实际折算:
0.14(人民币计价单位) × 7(固定汇率) = 0.98
也就是说,默认价格 = 阿里云官方原价的 98%(98 折)——比官方直采更省,且无需自建出海链路。
换算公式:本站每秒美元价 = 官方人民币原价 × 0.14(即 × 0.98 ÷ 7)。

价格明细(默认价,按秒计费)

HappyHorse-1.0 文生 / 图生 / 参考生视频同价,仅 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.6%(约 82 折)
档位等效价格(对比阿里云官方原价)算法
默认98%(98 折)倍率 0.14x × 固定汇率 7
叠加充值加赠(大客户最高档)约 81.6%(约 82 折)0.98 ÷ 1.2
  • 计费维度 = 分辨率档位 × 时长(秒),失败任务不计费。
  • 1:7 为固定结算汇率(不是优惠汇率),所有美元充值统一适用。
  • 充值加赠的最高加赠档位与适用渠道见 充值加赠活动。最新倍率以 控制台 为准。

⚠️ 端点选择(最重要)

API易 同时挂载两条路径,只有 DashScope 透传端点对 HappyHorse 全部能力完整可用
路径协议风格i2v / r2v 可用性结论
/v1/videosOpenAI 扁平风格❌ 媒体字段会被丢弃不要用
/wan/api/v1/services/aigc/video-generation/video-synthesisDashScope 原生透传✅ 完整可用始终用这条
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.0-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 字段

字段类型取值说明
resolutionstring720P / 1080P大写,建议显式指定
durationint2–15秒数(整数),常用 5 / 10
prompt_extendbooltrue / false智能改写 prompt,强烈推荐 true
watermarkbooltrue / false右下角「AI 生成」水印
seedint0–2147483647固定可提升可复现性
duration 必须是 整数 5 而不是字符串 "5"resolution大写 720P 更稳。

如何选择 HappyHorse 还是 Wan

HappyHorse 和 Wan 都是阿里系视频模型、共用同一端点和 schema(只改 model 名即可互换),侧重不同:
维度HappyHorse-1.0Wan2.7
音频驱动对口型(i2v)❌ 不支持,i2v 仅首帧wan2.7-i2v 支持 driving_audio
参考图生视频上限参考图最多 9 张参考图 + 参考视频合计 ≤5
视频编辑参考图≤5 张≤5 张
风格侧重高度还原动态画面,主体保持稳多主体互动、音色参考
需要多张参考图保持主体一致 → 选 happyhorse-1.0-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,typetask_error / parse_request_failed / build_request_failed改 body 重试(字段类型错、缺 media、用错端点)
执行阶段(上游阿里云拒)任务 status=failederror.message[InvalidParameter] / [InvalidImageUrl] 等方括号前缀打头看方括号提示,多为媒体 URL 不可达或 prompt 涉敏
建议客户端:HTTP 5xx / 网络错误做指数退避重试;HTTP 4xx 立刻 surface 不重试;任务 failed[InvalidImageUrl] 可重试,含 [InvalidParameter] / 敏感词不重试。

常见问题

没有。两者共用同一个 DashScope 透传端点、同一套请求结构、同一组 media type 名、同一个查询端点。切换只改 model 字段(如 wan2.7-t2vhappyhorse-1.0-t2v),body 其余部分一字不改。
happyhorse-1.0-i2v 不支持 driving_audio(音频驱动)字段,i2v 只接受 first_frame。做对口型 / rap / 数字人口播请用 Wan2.7-i2v
可以。官方说最多 9 张 reference_image,直接放在 media 数组里即可。多参考图能让主体/服装/场景一致性更强。
/v1/videos 对 i2v / r2v 的 media 字段适配不完整,会导致上游报 [InvalidParameter] Field required: input.media所有创建请求都走 /wan/api/v1/services/aigc/video-generation/video-synthesis,查询走 /v1/tasks/{task_id}
去掉 Authorization 头。result_url 已是 OSS 签好名的直链,再带 API易 Key 反而被 OSS 拒。result_url 默认 24 小时过期,请尽快下载落地。
status=failed 不扣费。但重复提交相同任务会重复计费,做好幂等。

相关文档

文生视频 Playground

happyhorse-1.0-t2v 在线调试

图生视频 Playground

happyhorse-1.0-i2v 首帧生成

参考图生视频 Playground

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

视频编辑 Playground

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

Wan 系列

同为阿里系,选型对照
HappyHorse 系列通过 API易 DashScope 透传通道提供。如有问题或建议,欢迎在 API易控制台 工单中反馈。