教程
通过 HiAPI API 调用 muse-video-1.0/text-to-video:curl 与 Python 指南
请求字段、异步轮询与可运行的示例请求
本页内容
发送之前:认证、端点与模型标识符
muse-video-1.0/text-to-video 能将文本提示词转换为生成的视频片段。你发送一个提示词和若干控制参数,服务渲染出片段,然后返回一个可下载的 URL 或引用。
关键的架构细节在于:此调用是异步的。视频渲染耗时较长,API 不会一直保持你的 HTTP 连接打开直到文件就绪。因此流程分为两个阶段:
- 提交——你 POST 提示词和参数。响应会很快返回,其中包含任务标识符和初始任务状态。
- 轮询——你按标识符间隔 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 模型端点,因此你在此处编写的客户端代码可复用。