如何通过 hiapi API 使用 happyhorse-1.1：文生视频、图生视频与参考生视频

如果你正在查找如何使用 happy horse 1.1，这里给出简短版本：happyhorse-1.1 不是一个模型端点，而是三个，它们都通过 hiapi 统一的异步任务 API 提供服务：

端点（模型 ID）	功能	必需输入
happyhorse-1.1/text-to-video	根据文本提示词生成视频	prompt
happyhorse-1.1/image-to-video	让静态图像动起来	image_urls
happyhorse-1.1/reference-to-video	在参考图像加提示词的引导下生成视频	prompt、reference_image

这三个端点共享相同的生命周期：POST /v1/tasks 提交 → 获取 taskId → 轮询 GET /v1/tasks/<id>（或接收回调）→ 下载 output[0].url。下面的每一张参数表和每一条错误消息都已针对线上 API 验证过——没有任何内容来自猜测。

前置条件

你只需要一样东西：hiapi API 密钥。从你的 hiapi 控制台 获取——它的形式类似 sk-...，放在 Authorization: Bearer 请求头中。视频生成按输出秒数计费；各端点当前的每秒费率见 定价页。

export HIAPI_KEY="sk-your-key-here"

最小可运行示例（文生视频）

提交任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

响应会在 data.taskId 下给你一个任务 ID。轮询它：

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

当 data.status 变为 success 时，视频 URL 位于 data.output[0].url。请立即下载——输出 URL 带有 expireAt 时间戳，且存放在临时存储中，因此请把它们当作取件窗口，而不是永久托管。

下面是同一流程的完整 Python 脚本（仅使用标准库）：

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

各端点的参数

输入 schema 是严格的：未知字段会被以 400 拒绝，而不是被静默忽略。size、seed、negative_prompt 和 audio 等字段都会返回 additional properties ... not allowed。以下是每个端点确切接受的参数。

happyhorse-1.1/text-to-video

字段	必需	类型	允许值
prompt	✅	string	你的场景描述
aspect_ratio	—	string	16:9、9:16、3:4、4:3、4:5、5:4、1:1、9:21、21:9
resolution	—	string	720p、1080p
duration	—	integer	3–15（秒）

含提示词技巧的完整讲解：happyhorse-1.1 文生视频教程。

happyhorse-1.1/image-to-video

字段	必需	类型	允许值
image_urls	✅	字符串数组	恰好 1 个可公开访问的图片 URL（maxItems: 1）
prompt	—	string	用于动画的运动/场景引导
resolution	—	string	720p、1080p
duration	—	integer	3–15（秒）

这里有两处容易让人踩坑。第一，image_urls 是数组，但当前只接受一个元素——请传 ["https://..."]，而不是裸字符串，也不是多个 URL。第二，此端点没有 aspect_ratio（API 会拒绝它）；输出画幅跟随你的源图像。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

深入阅读：happyhorse 图生视频教程。

happyhorse-1.1/reference-to-video

字段	必需	类型	允许值
prompt	✅	string	场景描述
reference_image	✅	字符串数组	1–9 个可公开访问的图片 URL（maxItems: 9）
aspect_ratio	—	string	与文生视频相同的 9 种比例
resolution	—	string	720p、1080p
duration	—	integer	3–15（秒）

这就是“保持我的角色/产品一致”的端点：参考图像锚定身份与风格，而提示词驱动动作。与图生视频不同，这里重新获得了 aspect_ratio 控制权，并且最多可以传 9 张参考图。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

深入阅读：happyhorse-1.1 参考生视频教程。

应该选择哪个端点？

• 你只有一个想法 → text-to-video。从文字到动态的最快路径。
• 你有想要做成动画的确切画面（产品图、插画、照片）→ image-to-video。源图像就是第一帧的样子。
• 你需要在多个片段中保持同一主体（一个角色、一个吉祥物、一个产品的多个角度）→ reference-to-video。参考图锁定身份；提示词按片段变化。

生产实践模式

用回调代替轮询

对于任何超出脚本范围的用途，请在创建任务时注册 webhook——视频任务耗时较长，而在 Web 请求处理器中轮询迟早会超时：

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

仅支持 "when": "final"——当任务到达终态时，你只会收到一次 POST（任何其他值都会返回 invalid callback.when: only 'final' is supported）。请将你的接收端设计为基于 taskId 幂等：在提交时存储任务 ID，并将重复或已处理过的回调视为无操作。保留一个低频轮询清扫器，作为因网络抖动而丢失回调时的兜底。

错误处理：三类失败

1. 校验错误（HTTP 400，INVALID_REQUEST）。 消息非常精确——读一下，它们会指出确切的字段：

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. 认证/权限错误（HTTP 401，permission_denied）。 密钥有误，或者密钥没有访问此模型的权限：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

请在 控制台 中检查密钥，如果联系支持，请附上 request_id。

3. 生成失败（任务 status: "fail"）。 提交成功但生成失败；轮询或接收回调时，错误详情位于任务对象的 error 字段中。这类错误值得通过退避重试——校验错误和认证错误则不值得。

成本控制

计费按生成的视频秒数进行，因此 duration 是你的主要成本杠杆——15 秒片段的花费是 5 秒片段的 3 倍，而 resolution 影响较小。用 duration: 3 和 720p 迭代提示词，然后按完整长度渲染最终版本。当前费率见 定价页。

相关阅读

• happyhorse-1.1 文生视频——模型页面与体验场
• happyhorse-1.1 图生视频——模型页面与体验场
• happyhorse-1.1 参考生视频——模型页面与体验场
• 使用 happyhorse-1.1 的短视频工作流
• hiapi 文档

常见问题

我可以同时使用图像和文本提示词吗？ 可以——image-to-video 在必需的 image_urls 之外还接受可选的 prompt，而 reference-to-video 同时要求 prompt 和 reference_image。只有 text-to-video 是仅用提示词。

我可以传多少张图片？ image-to-video：恰好一张（image_urls 上限为 1 个元素）。reference-to-video：reference_image 中最多九张。两者都接受可公开访问的 URL 数组，而不是上传文件或 base64。

happyhorse-1.1 支持 seed、negative_prompt 或 audio 参数吗？ 不支持。输入 schema 是严格的，会以 400 additional properties not allowed 错误拒绝这三者。如果你需要可复现性，请保持提示词和参数完全一致，并在你这边进行版本管理。

有哪些可用的分辨率和时长？ 所有三个端点：720p 或 1080p，以及 3 到 15 秒（整数）。如果省略，将应用默认值。

为什么我用一个看起来有效的密钥却收到 401 permission_denied？ 密钥存在，但不能使用此模型——这在限定范围或试用密钥中很常见。请在 控制台 中验证该密钥的模型权限，或生成一个新的无限制密钥。

如何在不轮询的情况下知道视频何时就绪？ 在提交时传入 callback: {"url": "...", "when": "final"}。当任务到达 success 或 fail 时，hiapi 会向你的 URL POST 一次。记住输出 URL 会过期——请在回调处理器中下载文件，不要热链它。