博客

教程

如何通过 HiAPI API 调用 happyhorse-1.1/text-to-video:可用的 curl 与 Python 示例

可用集成的请求结构、异步轮询与原生音频处理

2026年11月12日
封面图:深松绿色背景上,几块被剖分为平涂色面的抽象棱镜,以灰绿与雾绿色块构成克制的几何构图。
本页内容

本集成涵盖的内容

本指南将带你完成通过 HiAPI 统一 API 调用 happyhorse-1.1/text-to-video 的全过程。读完后,你将拥有一个可用的请求:提交文本提示词、轮询直至完成,并保存生成的视频及其原生音轨。我们会先介绍请求结构,让你在写任何代码之前理解请求负载;然后给出可直接复制的 curl 调用;接着解释视频生成所需的异步轮询模式;最后将全部内容移植到 Python,并加入基本的错误处理。无需具备视频 API 经验,你只需要一个 HiAPI API 密钥,以及终端或 Python 环境。目标是提供一份最小但完整的集成示例,你可据此改造为自己的流水线。

happyhorse-1.1/text-to-video 的请求结构

在发起调用之前,先理解构成文本转视频请求的字段会很有帮助。该端点接受一个 JSON 请求负载,其中至少包含模型标识符和你的文本提示词。其他常见字段用于控制输出尺寸和时长,但准确的参数名称和可接受值应以 HiAPI 上该模型的文档为准。一个有效的请求负载通常如下所示:

{
  "model": "happyhorse-1.1/text-to-video",
  "prompt": "日出时分,镜头缓缓横摇掠过薄雾笼罩的森林"
}

保持请求负载扁平,并且只使用模型文档中说明的字段。无法识别的字段或类型格式错误是请求被拒绝的最常见原因。如有疑问,先从仅包含 model 和 prompt 的最小负载开始,然后逐个添加可选参数,以便定位问题。

使用 curl 发起首次请求

请求负载准备好后,就可以使用 curl 提交任务。你将发送一个带有 JSON 请求体和 Authorization 头中 API 密钥的 POST 请求。响应通常会包含该任务的标识符,稍后你会用它轮询状态。以下是一个可用示例:

curl -X POST https://api.hiapi.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "日出时分,镜头缓缓横摇掠过薄雾笼罩的森林"
  }'

将 $HIAPI_API_KEY 替换为你的实际密钥,或在 shell 中导出它。响应将是 JSON,其中包含 id 字段(或类似命名的标识符)以及表示任务已被接受的状态。请仔细阅读响应:如果状态不是已接受状态,请先检查错误消息再继续。此时不要假设视频已经就绪;任务只是刚刚进入队列。

处理异步轮询

视频生成并非瞬时完成,因此 HiAPI 在初始响应中返回的是任务标识符,而不是最终视频。你需要轮询状态端点,直到任务达到终态。通用模式是:提交任务、获取 ID,然后以较短的间隔反复请求任务状态。当状态表示成功或失败时停止。以下是伪代码形式的逻辑:

  1. 提交任务并读取任务 id。
  2. 等待几秒钟。
  3. 使用该 id 请求任务状态。
  4. 如果状态为“completed”或“succeeded”,获取输出 URL 并退出循环。
  5. 如果状态为“failed”,记录错误并退出。
  6. 否则,再次等待并重复,直到达到合理的最大尝试次数。

避免过于频繁地轮询。对于视频任务,每次尝试之间间隔几秒钟通常就足够了。另外,不要指望某个单一的阻塞式响应会包含最终视频;异步模型是有意设计的,并且在所有长时间运行的生成任务中保持一致。

输出中的原生音频

由 happyhorse-1.1/text-to-video 生成的视频在输出中自带原生音频。任务完成时,响应会指向生成的视频文件,而该文件已经包含音轨。你无需单独生成或获取音频。要保存并验证结果,请从提供的 URL 下载视频文件,并保留其容器格式。如果你以程序方式处理该文件,请验证音频流是否存在,例如使用媒体工具检查文件。除非下游流水线要求,否则不要剥离或重新编码音频,因为这样做可能降低质量或完全移除音轨。请将返回的文件视为完整的视听资产。

用 Python 发起同样的请求

将 curl 调用移植到 Python 很直接:复用相同的 JSON 请求负载,并添加轮询循环。以下示例使用 requests,在每次尝试之间等待,并在失败时抛出异常。请将端点路径和状态字段名称替换为 HiAPI 上 happyhorse-1.1/text-to-video 文档中所述的内容。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "日出时分,镜头缓缓横摇掠过薄雾笼罩的森林",
}

resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]

for attempt in range(60):
    status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
    status_resp.raise_for_status()
    status = status_resp.json()
    state = status.get("status")
    if state in ("completed", "succeeded"):
        video_url = status["output"]["url"]
        print("视频已就绪:", video_url)
        break
    if state == "failed":
        raise RuntimeError(status.get("error", "生成失败"))
    time.sleep(5)
else:
    raise TimeoutError("轮询超时")

这遵循了前面描述的“轮询直至完成”逻辑。使用 raise_for_status() 尽早暴露 HTTP 错误,并保持合理的休眠间隔,以避免不必要的请求。

排查常见故障

大多数集成问题可归为几类。请求负载格式错误,例如缺少 model 字段或使用错误的 JSON 类型,会立即被拒绝;请对照模型文档仔细检查你的 JSON。轮询过于频繁可能导致速率限制或不必要的负载;请增大休眠间隔。把初始响应误当成最终视频是另一个常见错误;务必轮询直至终态。身份验证错误通常意味着缺少或格式错误的 Authorization 头,因此请验证你的 API 密钥是否已正确导出。最后,如果任务在轮询后失败,请检查状态响应中的错误消息;它通常指向无效的提示词或不支持的参数。修复这些问题后,先以最小的有效负载重试。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档