HappyHorse 视频生成
HappyHorse 是阿里云百炼的视频生成模型。在 AI Gateway 中，HappyHorse 使用服务化视频生成接口，不使用
/gateway/v1/chat/completions
/gateway/v1/chat/completions
。
一、适用模型
| 模型 | 类型 | 说明 |
|---|
happyhorse-1.0-t2v
happyhorse-1.0-t2v | 文生视频 | 根据文本提示词生成视频。 |
happyhorse-1.0-i2v
happyhorse-1.0-i2v | 图生视频 | 根据首帧图片和提示词生成视频。 |
happyhorse-1.0-r2v
happyhorse-1.0-r2v | 参考生视频 | 根据参考图片、角色或风格信息生成视频。 |
二、提交任务 Endpoint
POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/aigc/video-generation/video-synthesis
请求头：
Authorization: Bearer <API_KEY>
Content-Type: application/json
X-DashScope-Async: enable
视频生成通常是异步任务。提交任务后，响应中会返回任务 ID，业务系统再根据任务 ID 查询生成状态和结果。
三、文生视频
适用模型：
happyhorse-1.0-t2v
happyhorse-1.0-t2v
。
curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/aigc/video-generation/video-synthesis" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "happyhorse-1.0-t2v",
"input": {
"prompt": "一段 5 秒企业级 AI 网关产品视频：数据请求从多个业务系统进入统一网关，随后按策略路由到不同模型，画面干净、专业、科技感。"
},
"parameters": {
"size": "1280*720",
"duration": 5,
"prompt_extend": true
}
}'
四、图生视频
适用模型：
happyhorse-1.0-i2v
happyhorse-1.0-i2v
。
curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/aigc/video-generation/video-synthesis" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "happyhorse-1.0-i2v",
"input": {
"prompt": "让画面中的数据流缓慢移动，最终汇聚到中心的 AI Gateway 控制台，镜头轻微推进。",
"img_url": "https://example.com/first-frame.png"
},
"parameters": {
"size": "1280*720",
"duration": 5,
"prompt_extend": true
}
}'
五、参考生视频
适用模型：
happyhorse-1.0-r2v
happyhorse-1.0-r2v
。
参考生视频用于根据参考图保持人物、主体或风格一致。不同接入点对参考图字段可能有差异，以下为常见写法，正式接入请以模型广场示例为准。
curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/aigc/video-generation/video-synthesis" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "happyhorse-1.0-r2v",
"input": {
"prompt": "保持参考图中的产品外观不变，生成一段展示产品从左到右缓慢旋转的视频。",
"ref_img_url": "https://example.com/reference.png"
},
"parameters": {
"size": "1280*720",
"duration": 5,
"prompt_extend": true
}
}'
六、请求字段
| 字段 | 类型 | 必填 | 适用模型 | 说明 |
|---|
model
model | string | 是 | 全部 | 模型名称，例如 happyhorse-1.0-t2v
happyhorse-1.0-t2v 。 |
input
input | object | 是 | 全部 | 输入内容对象。 |
input.prompt
input.prompt | string | 是 | 全部 | 视频生成提示词，描述主体、动作、镜头、风格和质量要求。 |
input.img_url
input.img_url | string | 图生视频必填 | happyhorse-1.0-i2v
happyhorse-1.0-i2v | 首帧图片 URL。 |
input.ref_img_url
input.ref_img_url | string | 参考生视频常用 | happyhorse-1.0-r2v
happyhorse-1.0-r2v | 参考图片 URL。字段名以模型详情页为准。 |
parameters
parameters | object | 否 | 全部 | 生成参数。 |
parameters.size
parameters.size | string | 否 | 全部 | 视频分辨率，例如 1280*720
1280*720 。支持值以模型详情页为准。 |
parameters.duration
parameters.duration | integer | 否 | 全部 | 视频时长，单位通常为秒。支持范围以模型详情页为准。 |
parameters.prompt_extend
parameters.prompt_extend | boolean | 否 | 全部 | 是否开启提示词智能扩写。 |
parameters.seed
parameters.seed | integer | 否 | 全部 | 随机种子。用于提升同参数下结果可复现性。 |
parameters.watermark
parameters.watermark | boolean | 否 | 全部 | 是否添加水印。是否支持取决于模型。 |
parameters.fps
parameters.fps | integer | 否 | 全部 | 帧率。是否支持取决于模型。 |
提示词建议：
- 明确主体：画面中有什么。
- 明确动作：主体如何运动。
- 明确镜头：推近、拉远、环绕、平移、固定镜头等。
- 明确风格：真实摄影、产品演示、3D 渲染、手绘、科技感等。
- 明确约束：不要出现文字、不要变形、保持主体一致等。
七、提交任务响应
提交成功后通常会返回任务信息。
{
"output": {
"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"task_status": "PENDING"
},
"request_id": "xxxxxxxx"
}
| 字段 | 说明 |
|---|
output.task_id
output.task_id | 视频生成任务 ID。后续查询任务状态时使用。 |
output.task_status
output.task_status | 当前任务状态，例如 PENDING
PENDING 、RUNNING
RUNNING 、SUCCEEDED
SUCCEEDED 、FAILED
FAILED 。 |
request_id
request_id | 请求 ID。排查问题时使用。 |
八、查询任务结果
视频生成是异步任务。提交后需要根据
task_id
task_id
查询结果。
常见查询方式如下：
curl -X GET "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/tasks/<task_id>" \
-H "Authorization: Bearer $API_KEY"
如果模型广场详情页提供了专用查询示例，请以模型详情页中的查询地址为准。
成功响应通常包含视频 URL：
{
"output": {
"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://example.com/generated-video.mp4"
},
"usage": {
"video_duration": 5,
"video_count": 1
},
"request_id": "xxxxxxxx"
}
失败响应通常包含失败原因：
{
"output": {
"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"task_status": "FAILED",
"code": "InvalidParameter",
"message": "Invalid image url."
},
"request_id": "xxxxxxxx"
}
九、轮询建议
建议业务系统使用轮询方式查询任务结果：
- 提交视频生成任务。
- 保存
task_id
task_id
和业务单号。
- 每隔 3 到 5 秒查询一次任务状态。
- 如果状态为
SUCCEEDED
SUCCEEDED
，保存视频 URL。
- 如果状态为
FAILED
FAILED
，记录 code
code
、message
message
、request_id
request_id
并展示失败原因。
- 设置最大轮询时间，例如 10 分钟，避免无限等待。
Python 示例：
import time
import requests
api_key = "<your-api-key>"
submit_url = "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/aigc/video-generation/video-synthesis"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
payload = {
"model": "happyhorse-1.0-t2v",
"input": {
"prompt": "一段 5 秒企业级 AI Gateway 产品演示视频。"
},
"parameters": {
"size": "1280*720",
"duration": 5,
"prompt_extend": True,
},
}
submit_resp = requests.post(submit_url, headers=headers, json=payload, timeout=60)
submit_resp.raise_for_status()
task_id = submit_resp.json()["output"]["task_id"]
query_url = f"https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/tasks/{task_id}"
for _ in range(120):
query_resp = requests.get(query_url, headers={"Authorization": f"Bearer {api_key}"}, timeout=30)
query_resp.raise_for_status()
data = query_resp.json()
status = data.get("output", {}).get("task_status")
if status == "SUCCEEDED":
print(data["output"].get("video_url"))
break
if status == "FAILED":
raise RuntimeError(data["output"].get("message", "video generation failed"))
time.sleep(5)
else:
raise TimeoutError("video generation task timeout")
十、常见问题
为什么必须加 X-DashScope-Async: enable
X-DashScope-Async: enable
？
视频生成耗时较长，通常通过异步任务执行。该 Header 用于声明异步调用。
为什么图生视频失败？
常见原因包括图片 URL 不可访问、图片格式不支持、图片过大、图片内容不符合模型安全策略等。建议使用公网可访问的对象存储地址，并控制图片大小。
为什么生成视频和提示词不完全一致？
视频生成模型会根据提示词进行概率生成。可以通过更明确的主体、动作、镜头、风格和负面约束提升稳定性。
如何控制费用？
视频模型通常按生成时长、分辨率、模型类型等维度计费。生产环境建议限制
duration
duration
、
size
size
和并发数，并在用量统计中持续观察费用。
