HappyHorse 系列
- 文生视频、图生视频、参考生视频
- 计费只看分辨率与时长，与模式无关
- 首帧图与参考图不能混用
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
取值 happyhorse-1.1 或 happyhorse-1.0。
画面描述，上限 2500 字符，不支持特殊标记。
首帧，公网 URL 或 Base64 data URI。
格式 jpeg、jpg、png、bmp、webp，最短边至少 300 像素，宽高比 1:2.5 到 2.5:1，不超过 10MB。与 image_urls 互斥。
参考图，1 到 9 张。格式同上，单张不超过 10MB。与 first_frame_image 互斥。
取值 720P、1080P，默认 1080P。影响计费。
时长，3 到 15 秒，默认 5。影响计费。
输出画幅，取值 16:9、9:16、1:1、4:3、3:4，默认 16:9。
图生视频会忽略该字段，改用输入图片比例。
是否添加水印，默认 false。
随机种子，取值 0 到 2147483647。
为 true 时先做内容审查，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
happyhorse-1.1 or happyhorse-1.0.
The scene description, up to 2500 characters; special markup isn't supported.
The first frame, as a public URL or Base64 data URI.
Formats jpeg, jpg, png, bmp, webp; shortest side at least 300 pixels; aspect ratio 1:2.5 to 2.5:1; at most 10MB. Mutually exclusive with image_urls.
Reference images, 1 to 9. Same formats as above, at most 10MB each. Mutually exclusive with first_frame_image.
720P or 1080P, default 1080P. Affects billing.
Duration, 3 to 15 seconds, default 5. Affects billing.
Output framing: 16:9, 9:16, 1:1, 4:3, or 3:4, default 16:9.
Image to video ignores this field and uses the input image's ratio.
Whether to add a watermark; defaults to false.
Random seed, 0 to 2147483647.
When true, runs a content check first. Defaults to false.
模式判定
按以下优先级判定，命中即停：
- 只有
prompt—— 文生视频 prompt加first_frame_image—— 图生视频prompt加image_urls（1 到 9 张）—— 参考生视频
first_frame_image 与 image_urls 不能同时传，同时会出现返回 400 与错误码 mixed_media_not_allowed。
Judged in the following priority order, stopping at the first match:
- Only
prompt— text to video promptplusfirst_frame_image— image to videopromptplusimage_urls(1 to 9) — reference to video
first_frame_image and image_urls can't be passed together; passing both returns a 400 with the error code mixed_media_not_allowed.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
happyhorse-1.1 | 当前版本，三种模式统一入口 |
happyhorse-1.0 | 上一代，参数兼容 |
| Model ID | Positioning |
|---|---|
happyhorse-1.1 | Current version, one entry point for all three modes |
happyhorse-1.0 | Previous generation, parameter-compatible |
使用限制
- 首帧图与参考图互斥
- 5 到 10 秒是推荐区间：更短容易动作不连贯，更长会显著拉长上游处理时间
- 图生视频的画质高度依赖首帧：构图清晰、主体居中的首帧效果明显更好
- First-frame image and reference images are mutually exclusive
- 5 to 10 seconds is the recommended range: shorter tends to break motion continuity, longer noticeably stretches upstream processing time
- Image-to-video quality depends heavily on the first frame: a clear composition with a centered subject works noticeably better
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.