HappyHorse 1.0

HappyHorse 1.0 是阿里巴巴的视频生成与编辑模型，支持文生视频、首帧图生视频、参考生视频和视频编辑。

模型

模型名称	模式
`happyhorse-1.0-text-to-video`	文生视频
`happyhorse-1.0-image-to-video`	图生视频，基于首帧
`happyhorse-1.0-reference-to-video`	参考生视频，多参考图
`happyhorse-1.0-video-edit`	视频编辑

定价

按秒 × 分辨率计费：

分辨率	积分/秒
`720p`	27.5
`1080p`	48.5

视频编辑计费：(输入视频时长 + 输出视频时长) × 分辨率单价。

创建任务

POST https://api.aivideoapi.ai/v1/videos/generations

请求体

字段	类型	必填	说明
`model`	string	是	见上方模型列表
`input`	object	是	生成或编辑参数
`callback_url`	string	否	接收任务完成/失败通知的 URL

通用字段

字段	类型	必填	说明
`prompt`	string	是	文本提示词，最长 2500 字符
`resolution`	string	否	`720p` 或 `1080p`，默认 `720p`
`seed`	integer	否	`0` 到 `2147483647` 的整数

文生视频 Input

字段	类型	必填	说明
`aspect_ratio`	string	否	`16:9`、`9:16`、`1:1`、`4:3`、`3:4`，默认 `16:9`
`duration`	integer	否	3-15 秒，默认 `5`

图生视频 Input

字段	类型	必填	说明
`image_urls`	string[]	是	必须且只能传 1 张图片 URL，作为首帧
`duration`	integer	否	3-15 秒，默认 `5`

图生视频不支持 aspect_ratio，输出宽高比跟随首帧图片。

首帧图限制：仅支持公网 HTTP(S) URL，不支持 Base64；格式支持 JPEG、JPG、PNG、WEBP；宽和高均不低于 300 像素；宽高比需在 1:2.5 到 2.5:1 之间；文件大小不超过 20MB。

参考生视频 Input

字段	类型	必填	说明
`image_urls`	string[]	是	1-9 张参考图 URL
`aspect_ratio`	string	否	`16:9`、`9:16`、`1:1`、`4:3`、`3:4`，默认 `16:9`
`duration`	integer	否	3-15 秒，默认 `5`

在 prompt 中可以用 [Image 1]、[Image 2] 指代 image_urls 中对应顺序的参考图。

参考图限制：仅支持公网 HTTP(S) URL，不支持 Base64；格式支持 JPEG、JPG、PNG、WEBP；短边不低于 400 像素，推荐 720P 以上清晰图；文件大小不超过 20MB。避免传入过小、模糊或压缩过度的图像，以免影响效果。

视频编辑 Input

字段	类型	必填	说明
`video_urls`	string[]	是	必须且只能传 1 个待编辑视频 URL
`image_urls`	string[]	否	0-5 张参考图 URL
`audio_setting`	string	否	`auto` 或 `origin`

视频编辑不接受 duration 参数。输入视频时长必须为 3-60 秒；输出时长跟随输入视频并最多截取前 15 秒。计费公式为：(输入视频时长 + 输出视频时长) × 分辨率单价。

待编辑视频限制：仅支持公网 HTTP(S) URL；格式支持 MP4、MOV，建议 H.264 编码；时长 3-60 秒；长边不超过 2160 像素，短边不小于 320 像素；宽高比需在 1:2.5 到 2.5:1 之间；文件大小不超过 100MB；帧率大于 8fps。

参考图限制：仅支持公网 HTTP(S) URL，不支持 Base64；格式支持 JPEG、JPG、PNG、WEBP；宽和高均不低于 300 像素；宽高比需在 1:2.5 到 2.5:1 之间；文件大小不超过 20MB。

示例

文生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-text-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "雨夜霓虹街道中的电影感跟拍镜头",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

图生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-image-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "女孩缓慢转头，镜头轻轻推近",
      "image_urls": ["https://example.com/portrait.png"],
      "resolution": "1080p",
      "duration": 5
    }
  }'

参考生视频

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-reference-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "[Image 1]中的角色拿起[Image 2]中的折扇，镜头缓慢推近",
      "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/fan.jpg"
      ],
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

视频编辑

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "让视频中的角色穿上参考图里的条纹毛衣",
      "video_urls": ["https://example.com/input.mp4"],
      "image_urls": ["https://example.com/sweater.png"],
      "resolution": "720p",
      "audio_setting": "auto"
    }
  }'

响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

查询任务

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

状态变化：pending -> processing -> completed 或 failed。

任务失败时，预扣的积分会自动退还。

回调 (Callback)

创建任务时传入 callback_url，系统会在任务完成或失败时自动向你的 URL 发送 POST 请求。请求头与重试策略详见回调说明。

任务完成时回调

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "model": "happyhorse-1.0-text-to-video",
  "created_at": 1774790227,
  "completed_at": 1774790589,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/05/25/abc.mp4"
    ],
    "metadata": {
      "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "16:9"
      }
    }
  }
}

任务失败时回调

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "happyhorse-1.0-text-to-video",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "InvalidParameter: prompt 包含敏感词"
  }
}

重要说明

收到回调后请尽快返回 2xx 状态码（建议 3 秒内）。返回非 2xx 或超时（10 秒）将触发重试，最多 3 次（间隔分别为 3 分钟、10 分钟）。
业务侧应根据 X-Task-Id 做幂等处理，避免同一任务重复入库。
任务最终状态以 GET /v1/tasks/{taskId} 查询为准；如果 3 次回调都失败，仍可主动轮询兜底。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。