博客

教程

通过 HiAPI API 调用 muse-video-1.0/text-to-video:curl 与 Python 指南

请求字段、异步轮询与可运行的示例请求

2026年11月13日
抽象粗野主义封面图:混凝土平面处于斜射光下,暖灰色基调,青灰色阴影,还有一道细窄的鼠尾草绿色接缝。
本页内容

发送之前:认证、端点与模型标识符

muse-video-1.0/text-to-video 能将文本提示词转换为生成的视频片段。你发送一个提示词和若干控制参数,服务渲染出片段,然后返回一个可下载的 URL 或引用。

关键的架构细节在于:此调用是异步的。视频渲染耗时较长,API 不会一直保持你的 HTTP 连接打开直到文件就绪。因此流程分为两个阶段:

  1. 提交——你 POST 提示词和参数。响应会很快返回,其中包含任务标识符和初始任务状态。
  2. 轮询——你按标识符间隔 GET 任务,直到其状态变为终态(成功或失败),然后获取结果。

这种“先提交再轮询”的形态是写代码前最需要内化的要点。它改变了应用的结构:视频不会出现在提交请求的响应中,你遇到的任何错误都属于某个特定阶段——提交、校验、渲染或获取。在自己的代码中将这些阶段区分开(使用不同函数、分别记录日志),会让本指南的其余内容更容易应用。

传入的模型字符串必须精确:muse-video-1.0/text-to-video。vendor/model 形式是 HiAPI 各模型端点的通用约定,API 路由正是据此判断调用哪个生成器。

构建请求:提示词、时长与音频字段

首次请求前必须准备好三样东西。

API 密钥

每个请求都需通过 bearer token 认证。请将其存放在环境变量中而非源代码里,以免泄露到提交记录中:

export HIAPI_API_KEY="your_key_here"

以 Authorization: Bearer $HIAPI_API_KEY 请求头发送。如果请求因认证类错误而失败,请首先检查此请求头——变量名拼写错误、尾部空格或当前 shell 中未设置值是最常见的原因。

基础 URL

所有调用共用 HiAPI 平台的一个基础 URL。请使用账户面板或 API 参考中的当前值,不要从旧代码片段中复制;将其保存在变量中,以便只需修改一处。

模型标识符

模型字符串为 muse-video-1.0/text-to-video。请将其视为区分大小写的字面量。不要自行拼接或猜测变体,例如不同的大小写或缺失后缀——未知的模型标识符是校验错误,而非回退。

准备好这三要素后,就可以构建请求体了。

可用的 curl 请求

请求体为 JSON。从概念上讲,它包含三组字段。

提示词

提示词是创意指令,决定了大部分输出质量。有效的提示词应具体描述主体、动作、镜头行为、光照和风格,而不是仅堆砌形容词。这是一个普通字符串字段。

时长

文生视频模型需要知道片段应多长。时长是一个请求字段,也影响成本:生成为按输出秒数计费。由于可接受范围和默认值由模型在特定时间定义,请从 muse-video-1.0/text-to-video 的实时 API 参考中读取确切的字段名和允许值,不要猜测。传入超出范围的时长会导致校验失败。

音频

muse-video-1.0/text-to-video 在视觉生成之外还支持音频相关的控制。这些同样是请求字段——通常是开关或音频提示词风格的输入——其确切名称和可接受值在同一 API 参考中有文档说明。首次集成时,保守的做法是完全省略可选的音频字段,确认能成功返回视频后,再逐一叠加音频选项。

因此,最小请求体大致如下(字段名仅作示例——请对照参考确认):

{
  "model": "muse-video-1.0/text-to-video",
  "prompt": "日出时分,缓慢的空中镜头推过雾气缭绕的松树林,柔和的体积光,电影感",
  "duration": 5
}

由于参数集可能会演变,可靠的习惯是:获取该模型的参考文档,逐字复制字段名,并在发送前本地校验。

Python 中的相同请求

提交调用就是一个 HTTP POST。确切的资源路径由 HiAPI API 参考定义;下面的示例使用常规的任务端点,模型放在请求体中。

curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video-1.0/text-to-video",
    "prompt": "一个纸板机器人走过雨天霓虹小巷,湿沥青上的倒影,35mm 胶片质感",
    "duration": 5
  }'

响应很小且返回很快。其中重要的是任务标识符和状态。典型结构如下:

{
  "id": "job_abc123",
  "status": "queued"
}

记录 id——这是你后续所有调用的句柄。status 为 queued 或 processing 是正常现象,表示请求已被接受,而非出了问题。

在 shell 中手动轮询:

curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

间隔一段时间运行几次,观察 status 向终态变化。实践中,你希望把这个循环放在代码里,而不是终端历史中。

处理异步结果与轮询而不猛烈冲击 API

Python 版本做同样两件事——提交,然后轮询——但增加了超时处理、有界重试和结果保存,以便可安全地无人值守运行。

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}

MODEL = "muse-video-1.0/text-to-video"

def submit(prompt: str, duration: int) -> str:
    resp = requests.post(
        f"{BASE}/v1/video/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"model": MODEL, "prompt": prompt, "duration": duration},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for(job_id: str, max_wait: int = 900) -> dict:
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/video/generations/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        if r.status_code >= 500 or r.status_code == 429:
            time.sleep(interval)
            interval = min(interval * 2, 30)
            continue
        r.raise_for_status()
        job = r.json()
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(job.get("error") or "generation failed")
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in time")

def save(job: dict, path: str) -> None:
    url = job["result"]["video_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(8192):
                f.write(chunk)

if __name__ == "__main__":
    job_id = submit(
        "木桌上放着一个玻璃微型生态缸,晨光,尘埃微粒飘浮,微距",
        5,
    )
    job = wait_for(job_id)
    save(job, "output.mp4")
    print("saved output.mp4")

这里有三个深思熟虑的选择。重试由截止时间限定,而非循环次数,因此不会无限挂起。退避在瞬时失败时增长,在成功路径轮询时缓慢增长。下载是单独的流式请求,从而避免大文件走 JSON 路径。

常见错误及其排查方法

轮询频率是一个真实的设计决策。每 200 毫秒轮询一次只会产生无谓负载;每五分钟轮询一次则会在渲染完成后浪费实际时间。

实用策略:

  • 从适中的间隔(几秒)开始并逐渐增长——每次轮询乘以 1.5 倍,上限约半分钟,效果良好。
  • 对 429 和 5xx 响应加大退避:将间隔加倍并重试,将其视为容量信号而非任务状态。
  • 设置最大总等待时间,超时则抛出错误,而非永远轮询。更长时长的渲染确实耗时更久,因此上限应根据自身工作负载设定。
  • 仅在状态变化时记录一次转换,而非每次轮询——嘈杂的日志会让真正的失败难以察觉。

已完成任务的响应通常包含终态 status、任务 id,以及包含可下载视频 URL 的结果负载,有时附带元数据和 URL 过期时间。成功后请及时获取文件。如果任务报告 failed,在重试前阅读响应中的错误消息——校验失败永远不会因重试而成功,而内部渲染错误则可能成功。

下一步

从最小请求体开始,确认一次端到端成功运行,然后对照 muse-video-1.0/text-to-video 的当前参考文档添加时长和音频控制。同样的“先提交再轮询”模式可迁移到其他 HiAPI 模型端点,因此你在此处编写的客户端代码可复用。

立即开始构建持久 AI 产物

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

阅读 API 文档