HappyHorse AI

HappyHorse API 文档

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

API v1.0 Base URL: https://happyhorse.app

快速开始

bash
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 密钥。 → 获取 API 密钥

http
Authorization: Bearer YOUR_API_KEY

Generate 与 Status 工作流

HappyHorse 视频任务是异步的：先用 POST /api/generate 创建任务，保存返回的 task_id，再用 GET /api/status 查询，直到任务进入最终状态。

1

创建任务

把 prompt、model、mode、duration 和可选图片发送到 /api/generate。成功后接口会立刻返回 task_id。

2

轮询状态

用 task_id 请求 /api/status。status 为 IN_PROGRESS 时，视频仍在渲染，response 通常为 null。

3

读取结果

当 status 变为 SUCCESS 时，data.response.resultUrls[0] 就是视频 URL。如果变为 FAILED，展示 error_message 并停止轮询。

可用模型

HappyHorse 1.0

HappyHorse 1.0

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

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

API 端点

创建新的视频生成任务。model 字段必须设为 'happyhorse-1.0/video'。

请求体

请求体参数JSON
model:string

模型名称，必须为 'happyhorse-1.0/video'

prompt:optional string

视频描述文本（最多 2500 字符）。multi_shots 为 true 时非必填。

mode:optional string

质量模式：'pro' 或 'std'（默认：std） Defaults to std.

duration:optional number

视频时长（秒），3-15。多镜头模式下最终时长会根据 multi_prompt 自动汇总；如果显式传入 duration，请与各镜头时长总和保持一致。 Defaults to 5 / sum(multi_prompt).

aspect_ratio:optional string

输出宽高比（16:9, 9:16, 1:1） Defaults to 16:9.

image_urls:optional string[]

图生视频的图片 URL 数组。单镜头模式最多 2 个 URL（首帧 + 尾帧）；多镜头模式仅支持 1 个 URL（首帧）。提供图片后宽高比自动适配。

sound:optional boolean

启用原生音频生成（默认：true）。多镜头请求请显式传入 true 或 false。 Defaults to true.

cfg_scale:optional number

提示词遵循强度（0-1，默认 0.5）。值越高越严格遵循提示词。 Defaults to 0.5.

multi_shots:optional boolean

启用多镜头模式 Defaults to false.

multi_prompt:optional array

多镜头模式的 'prompt, duration' 对象数组（最多 5 个镜头，每段提示词最多 500 字符，每段时长 1-12 秒）

happyhorse_elements:optional array

元素对象数组。在提示词正文中，在对应元素的 name 前加上 @ 来引用（例如 name 为 element_dog 时，在提示里写 @element_dog）。每个元素：name（字符串）、description（字符串）、element_input_urls（2-4 张图片 URL）。每任务最多 3 个元素。

文生视频

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

图生视频

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

多镜头视频

json
{
  "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"
}

响应

Task created successfully

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

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

查询参数

查询参数
task_id:string

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

请求示例

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

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

javascript
// Extract video URL after the task is complete
const task = payload.data;
const videoUrl = task.status === "SUCCESS"
  ? task.response?.resultUrls?.[0]
  : null;

响应

{
  "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
  }
}

轮询最佳实践

视频生成需要一点时间，请把状态查询当作温和的后台任务处理，而不是高频循环请求。

先等待几秒

建议首次查询前等待约 8-10 秒，之后每 10-20 秒查询一次。更频繁的轮询不会让视频更快完成。

遇到最终状态就停止

SUCCESS 和 FAILED 都是最终状态。看到任一状态后立即停止轮询，并保存 task_id 方便客服排查或稍后查询。

设置客户端超时

等待 10-15 分钟后，停止当前主动等待，并允许用户手动再次查询状态。不要让浏览器标签页无限轮询。

错误时放慢重试

如果收到 429 或临时网络错误，请降低下一次请求频率。遇到 401 或 402 时，引导用户检查 API Key 或积分。

javascript
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForHappyHorseVideo(taskId) {
  const deadline = Date.now() + 15 * 60 * 1000;
  let delayMs = 8000;

  while (Date.now() < deadline) {
    const res = await fetch(
      `${BASE_URL}/api/status?task_id=${encodeURIComponent(taskId)}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );

    if (res.status === 429) {
      await sleep(Math.min(delayMs * 2, 30000));
      continue;
    }

    const payload = await res.json();
    if (!res.ok) {
      throw new Error(payload.message || `Status request failed: ${res.status}`);
    }

    const task = payload.data;
    if (task.status === "SUCCESS") {
      return task.response?.resultUrls?.[0];
    }
    if (task.status === "FAILED") {
      throw new Error(task.error_message || "Generation failed");
    }

    await sleep(delayMs);
    delayMs = Math.min(delayMs + 2000, 20000);
  }

  throw new Error("Timed out. Keep the task_id and check again later.");
}

API 测试工具

直接在浏览器中测试 API。将 YOUR_API_KEY 替换为您的实际 API 密钥。

API 测试POST

错误代码

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