快速开始

将 HappyHorse 1.0 视频生成 API 集成到您应用程序的完整指南。

curl -X POST 'https://happyhorse.app/api/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "happyhorse-1.0/video",
    "prompt": "A cinematic shot of mountains at sunrise",
    "mode": "pro",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

身份认证

所有 API 请求都需要在 Authorization 头中使用 Bearer 令牌进行身份验证。

获取 API 密钥: 您可以在控制面板的 API Keys 页面获取您的 API 密钥。

Authorization: Bearer YOUR_API_KEY

可用模型

HappyHorse 驱动的高质量 AI 视频生成

类型	描述	时长	积分
pro (text-to-video)	Pro 品质文生视频	3-15s	54/s (no audio) · 80/s (with audio)
pro (image-to-video)	Pro 品质图生视频	3-15s	54/s (no audio) · 80/s (with audio)
std (text-to-video)	标准品质文生视频	3-15s	40/s (no audio) · 60/s (with audio)
std (image-to-video)	标准品质图生视频	3-15s	40/s (no audio) · 60/s (with audio)

API 端点

POST /api/generate

model 字段必须设为 'happyhorse-1.0/video'。

参数名	说明
model	模型名称，必须为 'happyhorse-1.0/video'
prompt	视频描述文本（最多 2500 字符）。multi_shots 为 `true` 时非必填
mode	质量模式：'pro' 或 `std`
duration	视频时长（秒），3-15。多镜头模式下最终时长会根据 multi_prompt 自动汇总；如果显式传入 duration，请与各镜头时长总和保持一致。默认：`5`
aspect_ratio	输出宽高比（16:9, 9:16, 1:1）。默认：`16:9`
image_urls	图生视频的图片 URL 数组。单镜头模式最多 2 个 URL（首帧 + 尾帧）；多镜头模式仅支持 1 个 URL（首帧）。提供图片后宽高比自动适配
sound	启用原生音频生成（默认：`true`）。多镜头请求请显式传入 true 或 false
cfg_scale	提示词遵循强度（0-1）。默认：`0.5`。值越高越严格遵循提示词
multi_shots	启用多镜头模式。默认：`false`
multi_prompt	多镜头模式的 'prompt, duration' 对象数组（最多 5 个镜头，每段提示词最多 500 字符，每段时长 1-12 秒）
happyhorse_elements	元素对象数组。在提示词正文中，在对应元素的 name 前加上 @ 来引用（例如 name 为 element_dog 时，在提示里写 @element_dog）。每个元素：name（字符串）、description（字符串）、element_input_urls（2-4 张图片 URL）。每任务最多 3 个元素

文生视频

{
  "model": "happyhorse-1.0/video",
  "prompt": "A majestic eagle soaring through clouds at sunset",
  "mode": "pro",
  "duration": 5,
  "aspect_ratio": "16:9",
  "sound": true
}

图生视频

{
 "model": "happyhorse-1.0/video",
 "prompt": "The character slowly turns and smiles",
 "mode": "pro",
 "image_urls": ["https://example.com/my-image.jpg"],
 "duration": 5
}

多镜头视频

{
  "model": "happyhorse-1.0/video",
  "mode": "pro",
  "multi_shots": true,
  "sound": true,
  "duration": 10,
  "multi_prompt": [
    { "prompt": "A woman walks into a coffee shop", "duration": 3 },
    { "prompt": "She orders a latte and sits by the window", "duration": 4 },
    { "prompt": "She looks outside and smiles", "duration": 3 }
  ],
  "aspect_ratio": "16:9"
}

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "IN_PROGRESS"
  }
}

GET /api/status

使用生成接口返回的 task_id 检查视频生成任务的状态。

查询参数

task_id: string - 生成接口返回的唯一任务 ID（以 n92 开头）

请求示例

curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

response 字段包含 resultUrls 数组。通过 data.response.resultUrls[0] 获取视频 URL。

// Extract video URL from response
const videoUrl = data.response.resultUrls[0];

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "SUCCESS",
    "consumed_credits": 400,
    "created_at": "2026-04-08T10:30:00Z",
    "type": "text-to-video",
    "request": {
      "model": "happyhorse-1.0/video",
      "prompt": "A majestic eagle soaring through clouds at sunset",
      "mode": "pro",
      "duration": 5,
      "aspect_ratio": "16:9"
    },
    "response": {
      "resultUrls": [
        "https://cdn.example.com/videos/abc123.mp4"
      ]
    },
    "error_message": null
  }
}

错误代码

HTTP 状态	代码	说明
400 错误请求	`INVALID_PROMPT`	提示词无效或为空
400 错误请求	`INVALID_DURATION`	时长超出支持范围（3-15秒）
400 错误请求	`INVALID_MODEL`	模型必须为 'happyhorse-1.0/video'
401 未授权	`INVALID_API_KEY`	API 密钥缺失或无效
402 需要付费	`INSUFFICIENT_CREDITS`	积分不足
429 请求过多	`RATE_LIMITED`	请求过于频繁，请稍后再试
500 服务器错误	`INTERNAL_ERROR`	服务器错误，请稍后重试