HappyHorse 文档客户 API
使用 HappyHorse API 创建视频、上传参考素材并轮询生成状态。
可用状态
HappyHorse Customer API 已通过 /api/v1 向客户集成开放。当你的工作区已启用
API Key 后，即可使用 Customer API。如果你看不到 API Keys 页面，请联系
HappyHorse 管理员或支持人员。
启用访问后，登录用户可以在 Dashboard / Settings / API Keys 创建和管理密钥。 创建密钥后，请复制仅显示一次的完整 secret，安全保存，并删除不再使用的密钥。
所有请求都使用 Bearer Token：
Authorization: Bearer hh_live_your_api_key基础 URL
请使用你的 HappyHorse 生产域名作为基础 URL：
https://<your-happyhorse-domain>下面的示例默认你已经设置：
export HAPPYHORSE_API_KEY="hh_live_your_api_key"
export HAPPYHORSE_BASE_URL="https://<your-happyhorse-domain>"认证方式
每个 Customer API endpoint 都需要 Authorization header。缺少、无效或被限流
的密钥会返回下文定义的稳定错误格式。
curl "$HAPPYHORSE_BASE_URL/api/v1/videos/example-id" \
-H "Authorization: Bearer $HAPPYHORSE_API_KEY"上传参考素材
POST /api/v1/uploads/presign 用于为视频参考素材创建短期有效的上传 URL。
接口会返回一个 storage key；创建视频时把这个 key 传给
POST /api/v1/videos。
HappyHorse 当前支持客户直接上传以下素材：
| 类型 | Content types | 最大大小 |
|---|---|---|
image | image/png, image/jpeg, image/webp | 10 MB |
video | video/mp4, video/quicktime, video/webm | 50 MB |
audio | audio/mpeg, audio/mp3, audio/wav, audio/webm | 15 MB |
如果录音工具导出的是 audio/mp4，请先转换为当前接受的音频 MIME 类型再上传。
当前 API 会对不支持的类型返回 upload_type_not_supported。
请求
{
"kind": "image",
"contentType": "image/png",
"sizeBytes": 5242880
}kind 可省略，默认是 image。sizeBytes 必须是即将上传文件的准确大小。
响应
{
"uploadUrl": "https://storage.example.com/presigned-url",
"key": "videos/inputs/user-id/asset-id.png",
"publicUrl": "https://cdn.example.com/videos/inputs/user-id/asset-id.png",
"kind": "image"
}你可以先创建 presign 并保存响应，再从响应里取出 uploadUrl 和 key，最后用
相同的 content type 和文件大小上传文件：
curl -X POST "$HAPPYHORSE_BASE_URL/api/v1/uploads/presign" \
-H "Authorization: Bearer $HAPPYHORSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "image",
"contentType": "image/png",
"sizeBytes": 5242880
}' > presign.json
UPLOAD_URL="$(jq -r '.uploadUrl' presign.json)"
SOURCE_IMAGE_KEY="$(jq -r '.key' presign.json)"
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
--data-binary "@reference.png"创建视频时，把 SOURCE_IMAGE_KEY 作为 sourceImageKey。如果上传的是参考视频或
音频，则把取出的 key 作为 referenceVideoKey 或 referenceAudioKey。
常见错误包括 invalid_input、upload_file_too_large、
upload_type_not_supported、missing_api_key、invalid_api_key、
rate_limited 和 internal_error。
创建视频
POST /api/v1/videos 会启动一个异步视频生成任务。接口会立即扣除积分、把任务
加入队列，并返回视频 ID。请轮询 GET /api/v1/videos/{id}，直到状态变为
ready 或 failed。
模型由客户当前套餐自动选择。当前 API 不接受 model 字段。
请求
{
"prompt": "A cinematic shot of a chestnut horse running through a sunlit meadow",
"style": "cinematic",
"durationSec": 6,
"aspectRatio": "16:9",
"resolution": "720p",
"sourceImageKey": "videos/inputs/user-id/asset-id.png",
"referenceVideoKey": "videos/reference-video/user-id/clip-id.mp4",
"referenceAudioKey": "videos/reference-audio/user-id/audio-id.mp3",
"cameraMotion": "pan-right",
"motionIntensity": 3,
"cfgScale": 0.5
}支持字段：
| 字段 | 类型 | 说明 |
|---|---|---|
prompt | string | 必填，3 到 2000 个字符。 |
style | string | 可选，最多 50 个字符。 |
durationSec | integer | 必填，3 到 12 秒。套餐限制会生效。 |
aspectRatio | enum | 可选，默认 16:9。可选值：16:9、9:16、1:1。 |
resolution | enum | 可选，默认 720p。可选值：720p、1080p。 |
sourceImageKey | string | 可选，上传预签接口返回的首帧/参考图片 key。 |
lastFrameKey | string | 可选，尾帧图片 key。不能与 sourceImageKey 同时使用。 |
referenceVideoKey | string | 可选，上传预签接口返回的参考视频 key。 |
referenceAudioKey | string | 可选，上传预签接口返回的参考音频 key。 |
cameraMotion | enum | 可选，默认 none。可选值：none、static、pan-left、pan-right、tilt-up、tilt-down、zoom-in、zoom-out、orbit。 |
motionIntensity | integer | 可选，1 到 5。 |
cfgScale | number | 可选，0 到 1。 |
当前 API 使用 HappyHorse storage key 作为输入素材引用，不接受任意外部
inputImageUrl、referenceVideoUrl 或 audioUrl 字段。请先调用
POST /api/v1/uploads/presign，上传素材，再传入响应中的 key。
响应
{
"id": "018f3f1d-8c2e-7b4d-9db1-8e8f3a0c8f21",
"status": "queued"
}示例：
curl -X POST "$HAPPYHORSE_BASE_URL/api/v1/videos" \
-H "Authorization: Bearer $HAPPYHORSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cinematic shot of a chestnut horse running through a sunlit meadow",
"style": "cinematic",
"durationSec": 6,
"aspectRatio": "16:9",
"resolution": "720p"
}'积分和套餐错误：
insufficient_credits，HTTP 402，表示账号积分不足，无法支付当前时长和清晰度。plan_gate_exceeded，HTTP 403，表示当前套餐不允许某个设置，例如时长、参考音频、 尾帧输入或其他受限功能。响应会包含field、requiredPlan和currentPlan。
查询视频状态
GET /api/v1/videos/{id} 返回单个视频的当前状态。API Key 只能读取该密钥所属
用户创建的视频。其他账号的视频会返回 not_found。
curl "$HAPPYHORSE_BASE_URL/api/v1/videos/018f3f1d-8c2e-7b4d-9db1-8e8f3a0c8f21" \
-H "Authorization: Bearer $HAPPYHORSE_API_KEY"响应：
{
"id": "018f3f1d-8c2e-7b4d-9db1-8e8f3a0c8f21",
"status": "ready",
"prompt": "A cinematic shot of a chestnut horse running through a sunlit meadow",
"style": "cinematic",
"durationSec": 6,
"aspectRatio": "16:9",
"resolution": "720p",
"videoUrl": "https://cdn.example.com/videos/outputs/018f3f1d.mp4",
"thumbnailUrl": null,
"errorMessage": null,
"readyAt": "2026-04-26T12:30:00.000Z"
}常见状态包括 queued、processing、ready 和 failed。在素材生成前，
videoUrl 和 thumbnailUrl 为 null。如果生成失败，status 会变为
failed，errorMessage 会描述失败原因。
错误格式
Customer API 错误使用稳定 JSON envelope：
{
"error": {
"code": "invalid_input",
"message": "Request body is invalid."
}
}部分错误会包含额外字段：
{
"error": {
"code": "plan_gate_exceeded",
"message": "Your plan does not allow this video setting.",
"field": "referenceAudio",
"requiredPlan": "pro",
"currentPlan": "basic"
}
}主要错误码：
| Code | HTTP | 含义 |
|---|---|---|
missing_api_key | 401 | 未提供 Bearer token。 |
invalid_api_key | 401 | token 缺失、已删除、格式错误或无效。 |
rate_limited | 429 | API Key 超出限流。 |
invalid_input | 400 | JSON body 或路由输入未通过校验。 |
insufficient_credits | 402 | 账号积分不足。 |
plan_gate_exceeded | 403 | 当前套餐不允许请求的设置。 |
upload_file_too_large | 413 | 上传文件超过对应类型的最大大小。 |
upload_type_not_supported | 400 | 当前上传类型不接受该 MIME 类型。 |
not_found | 404 | 视频不存在，或不属于当前 API Key 所属账号。 |
internal_error | 500 | HappyHorse 无法完成请求。 |
Webhook
HappyHorse 目前还没有面向客户的视频状态 webhook endpoint。集成方应轮询
GET /api/v1/videos/{id}，直到状态变为 ready 或 failed。大多数任务可以
使用 5 到 10 秒的轮询间隔。