HappyHorse 视频生成
curl --request POST \
--url https://api.gravitex.ai/v1/video/generations \
--header 'Authorization: <authorization>'视频系列
HappyHorse 视频生成
阿里 HappyHorse 文生视频、图生视频、参考生视频
POST
/
v1
/
video
/
generations
HappyHorse 视频生成
curl --request POST \
--url https://api.gravitex.ai/v1/video/generations \
--header 'Authorization: <authorization>'Documentation Index
Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
Use this file to discover all available pages before exploring further.
简介
HappyHorse（快马）是阿里云百炼推出的视频生成系列，由文生视频（HappyHorse-T2V）、图生视频（HappyHorse-I2V）与参考生视频（HappyHorse-R2V）组成，主打物理真实、运动流畅的高质量视频输出。全系列支持 720P 与 1080P 输出，时长 3–15 秒。 通过 GravitexAI 统一视频接口调用：先 提交视频任务 获取task_id，再 查询视频任务 轮询状态并获取 url。
HappyHorse 的请求体通过
metadata.input 与 metadata.parameters 传递底层 DashScope 参数，与万相 2.7 结构相同。参考生视频在 prompt 中使用 [Image 1]、[Image 2] 指代参考图（英文方括号格式），且仅支持图片参考，不支持视频参考。认证
Bearer Token，如
Bearer sk-xxxxxxxxxx支持的模型
| 模型 ID | 说明 | 支持分辨率 | 最大时长 | 特点 |
|---|---|---|---|---|
happyhorse-1.0-t2v | 文生视频 | 720P、1080P | 15 秒 | 文本语义理解、多宽高比 |
happyhorse-1.0-i2v | 图生视频（首帧） | 720P、1080P | 15 秒 | 首帧驱动，画幅跟随输入图 |
happyhorse-1.0-r2v | 参考生视频 | 720P、1080P | 15 秒 | 最多 9 张参考图，主体融合 |
调用流程
- 提交任务：
POST /v1/video/generations，传入model、prompt、duration及metadata中的 HappyHorse 参数。 - 轮询状态：
GET /v1/video/generations/{task_id}，建议每 3–15 秒查询一次，直到status为succeeded或failed。 - 获取结果：成功时响应中的
url为视频地址（有效期通常为 24 小时，请及时下载转存）。
通用请求结构
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID，见上表 |
prompt | string | 视场景 | 视频生成提示词（与 metadata.input.prompt 一致） |
duration | integer | 否 | 视频时长（秒），与 metadata.parameters.duration 保持一致 |
metadata.input | object | 是 | 输入：prompt、media 等 |
metadata.parameters | object | 否 | 处理参数：resolution、ratio、duration、watermark、seed 等 |
提交成功响应
{
"task_id": "video_69095b4ce0048190893a01510c0c98b0",
"status": "submitted",
"format": "mp4"
}
查询成功响应
{
"task_id": "video_69095b4ce0048190893a01510c0c98b0",
"status": "succeeded",
"format": "mp4",
"url": "https://gravitex-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/video.mp4"
}
使用场景
- 文生视频 (T2V)
- 图生视频 (I2V)
- 参考生视频 (R2V)
基于文本提示词生成物理真实、运动流畅的视频。文生视频示例：
文本提示词，描述期望生成的视频内容
720P 或 1080P宽高比：
16:9、9:16、1:1、4:3、3:4、4:5、5:4、9:21、21:9视频时长（秒），取值范围 3–15
是否添加水印（右下角固定文案「Happy Horse」）
随机种子，范围
[0, 2147483647]，用于提升可复现性curl -X POST "https://api.gravitex.ai/v1/video/generations" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-t2v",
"prompt": "一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。一列硬纸板火车缓缓驶过，小灯点缀其间，照亮前路。",
"duration": 5,
"metadata": {
"input": {
"prompt": "一座由硬纸板和瓶盖搭建的微型城市，在夜晚焕发出生机。一列硬纸板火车缓缓驶过，小灯点缀其间，照亮前路。"
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5,
"watermark": false
}
}
}'
以首帧图片为基础，通过文本描述引导生成视频。画幅自动跟随首帧图像，不支持
首帧生视频示例：
ratio 参数。media 类型
| type | 说明 | 数量限制 |
|---|---|---|
first_frame | 首帧图像 | 有且仅有 1 张 |
文本提示词，描述首帧图像如何动起来（可选）
媒体列表，包含 1 个
first_frame 对象，每项含 type 与 url720P 或 1080P。模型根据分辨率档位自动缩放，输出宽高比与首帧近似一致视频时长（秒），取值范围 3–15
是否添加水印
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-i2v",
"prompt": "一只猫在草地上奔跑",
"duration": 5,
"metadata": {
"input": {
"prompt": "一只猫在草地上奔跑",
"media": [
{"type": "first_frame", "url": "https://example.com/first_frame.png"}
]
},
"parameters": {
"resolution": "720P",
"duration": 5,
"watermark": false
}
}
}'
支持传入 1–9 张参考图像，通过文本提示词描述场景，将图像中的主体角色融合生成流畅视频。在
多参考图示例：
prompt 中使用 [Image 1]、[Image 2] 指代 media 数组中对应位置的参考图（顺序一致）。media 类型
| type | 说明 | 数量限制 |
|---|---|---|
reference_image | 参考图像 | 1–9 张 |
使用
[Image n] 指代参考素材的提示词，需指明参考图中的具体对象，例如「[Image 1] 中身着红色旗袍的女性」参考图像列表，第 1 个元素对应
[Image 1]，第 2 个对应 [Image 2]，以此类推720P 或 1080P宽高比：
16:9、9:16、1:1、4:3、3:4、4:5、5:4、9:21、21:9视频时长（秒），取值范围 3–15
是否添加水印
curl -X POST "https://api.gravitex.ai/v1/video/generations" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-r2v",
"prompt": "[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。",
"duration": 5,
"metadata": {
"input": {
"prompt": "[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。",
"media": [
{"type": "reference_image", "url": "https://example.com/girl.jpg"},
{"type": "reference_image", "url": "https://example.com/fan.jpg"},
{"type": "reference_image", "url": "https://example.com/earrings.jpg"}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5,
"watermark": false
}
}
}'
参数参考
通用 parameters
| 参数 | 类型 | 说明 |
|---|---|---|
duration | integer | 3–15 秒，默认 5 |
resolution | string | 720P 或 1080P，默认 1080P |
watermark | boolean | 是否添加水印，默认 true |
seed | integer | 随机种子，范围 [0, 2147483647] |
文生视频 & 参考生视频
| 参数 | 类型 | 说明 |
|---|---|---|
ratio | string | 16:9、9:16、1:1、4:3、3:4、4:5、5:4、9:21、21:9，默认 16:9。图生视频（i2v）由首帧决定画幅，无需传 ratio |
媒体输入限制
| 类型 | 格式 | 大小 | 其他限制 |
|---|---|---|---|
| 首帧图像（first_frame） | JPEG、JPG、PNG、WEBP | ≤ 20MB | 宽和高不小于 300 像素 |
| 参考图像（reference_image） | JPEG、JPG、PNG、WEBP | ≤ 20MB | 短边不低于 400 像素，推荐 720P 以上清晰图；1–9 张 |
错误处理
| HTTP 状态码 | 含义 | 建议 |
|---|---|---|
| 400 | 请求参数错误 | 检查 metadata 结构与媒体限制 |
| 401 | 未授权 | 检查 API Key |
| 429 | 请求过于频繁 | 降低频率后重试 |
| 502 | 上游服务错误 | 稍后重试 |
status 为 failed，error.message 包含具体原因。
常见问题
生成的视频链接有效期多久？
生成的视频链接有效期多久？
视频
url 与 task_id 有效期通常为 24 小时。建议获取后立即下载并转存至自有存储。参考生视频如何指代参考图？
参考生视频如何指代参考图？
在 prompt 中使用
[Image 1]、[Image 2] 等英文方括号格式，顺序与 media 数组中 reference_image 的顺序一致。需明确描述参考图中的具体对象。图生视频支持哪些模式？
图生视频支持哪些模式？
HappyHorse 图生视频仅支持 首帧（
first_frame）模式，不支持首尾帧、视频续写或音频驱动。与万相 2.7 的调用方式有何不同？
与万相 2.7 的调用方式有何不同？
结构相同，均使用
metadata.input / metadata.parameters 与 media 数组。主要差异：HappyHorse 参考生视频使用 [Image n] 指代且仅支持图片（最多 9 张）；万相 2.7 使用「图n / 视频n」并支持视频参考与音色复刻。HappyHorse 默认分辨率 1080P、默认添加水印，时长范围为 3–15 秒。相关接口
提交视频任务
统一视频任务提交入口与多模型参数说明
查询视频任务
轮询任务状态并获取视频 URL
⌘I