教程
如何通过 HiAPI API 使用 pixverse-v6-max/text-to-video:curl、Python 与可运行的请求示例
本页内容
这个端点做什么,以及何时使用
pixverse-v6-max/text-to-video 是 HiAPI 上的文生视频端点。你发送一段描述所需场景的文本提示词,端点返回渲染好的视频。由于视频生成需要时间,该端点是异步的:初次请求不会直接返回视频,而是返回一个任务标识符,你用它来查询进度并获取最终结果。
这种“请求—确认—轮询”的形态是本教程所有内容的核心心智模型。内部流程始终一致:
- 使用提示词和参数提交生成任务。
- 立即收到任务标识符。
- 轮询该任务,直到其报告完成(或失败)。
- 下载或嵌入结果视频的 URL。
何时适合使用这个端点
当你手头只有描述、没有源素材时,就选 pixverse-v6-max/text-to-video——例如根据文字简报制作产品预告、为应用生成背景片段、制作分镜预览。如果你已有图片并希望让它动起来,那属于图生视频工作流,不是这个端点。如果你希望模型以对话方式反复迭代提示词,那属于另一种交互方式。这个端点是从文本到视频的直接、单次生成路径。
由于生成是异步的,它也适合基于队列的架构:Web 后端接收用户请求、提交任务,然后由工作进程轮询并稍后交付结果。整个调用过程中不会有任何环节阻塞到完整渲染结束。
开始之前:鉴权与请求基础
在编写任何代码之前,先确认三件事。
1. 一个 API 密钥
每个 HiAPI 请求都需要用 API 密钥鉴权。把它当作密码对待:不要提交到源码仓库,从环境变量加载,一旦泄露就立即轮换。下面的示例从 HIAPI_API_KEY 读取它,因此请先在 shell 中导出:
export HIAPI_API_KEY="your_key_here"
2. 正确的基础 URL
所有请求都发往 HiAPI API 基础 URL,并附加端点路径。请使用你 HiAPI 账户中记录的 base URL,而不要从博客文章中硬编码主机名——如果不确定,请查看仪表盘中的 API 参考文档。下面的示例用 $HIAPI_BASE_URL 作为该值的占位符。
3. JSON 约定
提交和状态查询都是基于 HTTPS 的 JSON:
- 对每个带请求体的请求发送
Content-Type: application/json。 - 对每个请求(包括状态查询)发送
Authorization: Bearer $HIAPI_API_KEY。 - 预期返回 JSON,包括出错时也是如此——要读取错误响应体,而不只看 HTTP 状态码。
快速健全性检查
如果你有可用的轻量级端点(例如 models 或 account 路由),在触碰视频端点之前先调用一次。那里返回 200 就证明你的密钥、base URL 和请求头格式都正确,从而在后续调试中排除三个变量。
一个可运行的 curl 请求
以下是完整的提交调用。端点路径是 pixverse-v6-max/text-to-video;请求体携带你的提示词和生成参数。
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "夜晚,一条被雨水浸湿的霓虹小巷,缓慢推轨镜头,电影感",
"duration": 5,
"aspect_ratio": "16:9"
}'
逐字段说明
prompt—— 文本描述。要明确主体、运动、镜头运动和氛围。这是影响输出质量最重要的杠杆。duration—— 请求的片段时长。参见下文的时长与宽高比部分。aspect_ratio—— 输出画面比例,例如16:9、9:16、1:1。
返回什么
提交成功会返回一个包含任务标识符的 JSON 对象——即用于轮询的句柄。具体字段名请以 API 参考文档为准;在本教程中我们称其为 task_id。把它保存下来:
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"夜晚,一条被雨水浸湿的霓虹小巷,缓慢推轨镜头,电影感","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
注意响应中不包含什么:视频。生成在后台运行。请把提交响应当作回执,而不是结果。
相同请求的 Python 版本
Python 版本与 curl 调用完全对应。为简洁起见我们使用 requests,但 httpx 或 urllib 同样可行——唯一要求是相同的请求头和 JSON 请求体。
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"prompt": "夜晚,一条被雨水浸湿的霓虹小巷,缓慢推轨镜头,电影感",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# 输出服务端的错误响应体——它通常会指出出问题的字段
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
值得照抄的要点
json=payload会自动序列化请求体并设置内容类型。如果你改用data=json.dumps(payload),则需保留显式的Content-Type请求头。- 提交时设置客户端超时可以防止连接挂起。它并不限制生成时间——生成发生在服务端,这正是需要轮询的原因。
- 先检查状态码再解析。 4xx 响应体通常比状态码本身提供更多信息;把它打印出来。
- 绝不记录 API 密钥。 改为记录
task_id——它可以安全存储,且是你的调试句柄。
时长与宽高比参数
这两个字段是请求被拒的最常见来源,因此值得认真对待。
duration
duration 设置请求的片段长度,单位为秒。可请求的取值受端点支持范围限制;发送超出该范围的值通常会产生参数校验错误,而不是静默截断片段。请从 API 参考文档中记录的支持值中选取,并保持为整数。片段越长,渲染耗时越久,因此在开发阶段优先使用支持的最短时长——你验证的是流程链路,不是摄影艺术。
aspect_ratio
aspect_ratio 是形如 W:H 的字符串。要让它匹配视频最终展示的位置:
16:9—— 横屏:网站主视觉区、YouTube 风格播放器、桌面背景。9:16—— 竖屏:移动端短视频信息流和故事。1:1—— 正方形:网格布局和缩略图。
在这里选错形状修复成本很低,但发现得太晚代价很高:重新渲染要再消耗一个完整生成周期,因此在提交前就应确定目标展示场景。
被拒绝时该检查什么
- 类型不匹配 ——
duration写成字符串("5")而不是数字,或aspect_ratio写成两个数字。保持 duration 为数值、aspect ratio 为字符串。 - 不支持的值 —— 时长或比例超出文档记录的范围。请逐项对照参考列表。
- 字段命名 —— 像
aspectRatio或durationSeconds这样的拼写错误,最好的情况也只是被当作未知字段静默处理。请从参考文档复制字段名。
快速定位问题字段的方法:先只带 prompt 重新提交,然后逐个加回参数。第一次被拒就能指出问题字段。
轮询异步任务直到视频就绪
轮询是一个循环,遵循三条规则:检查状态、休眠、在终态停止。再加上一个上限,避免卡住的任务无限空转。
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # 状态路由见 API 参考文档
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # 温和退避,设有上限
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
为什么退避很重要
对一个需要一分钟的生成任务每秒固定轮询一次,会浪费几十次请求。从小间隔开始逐步增大——上面的上限倍数会稳定在舒适的间隔,而不会频繁冲击 API。如果你要运行许多任务,用队列加单个轮询工作进程,比每个请求一个循环更友好。
处理结果
任务成功后,响应会携带视频 URL。请及时获取,若结果需要留存,请复制到你自己的存储——签名 URL 并非永久有效。在把文件交给用户之前,检查下载时的内容类型和大小,并将 task_id 与存储的资产一起记录,这样将来任何问题都能追溯到确切的生成记录。
排查常见错误
调用失败时,按此清单逐项排查。大多数失败属于以下四类之一。
鉴权与访问
- 401 / unauthorized —— 密钥缺失、格式错误或未发送。确认请求头精确为
Authorization: Bearer <key>,并确认发起调用的 shell 或进程中该环境变量确实已赋值。 - 403 / forbidden —— 密钥有效,但不允许访问此端点。在仪表盘中检查该密钥的权限范围。
请求校验
- 400 / 422 —— JSON 格式错误或字段值有误。打印完整的错误响应体;它通常会指出字段。重新检查
duration类型和aspect_ratio字符串格式。 - 提交时 404 —— 端点路径错误。确认路径精确为
pixverse-v6-max/text-to-video,且你的 base URL 没有重复或缺失的路径段。
任务级失败
- 状态为
failed—— 任务被接受但生成失败。阅读任务上的错误消息;它能区分内容拒绝和内部故障。提示词被拒是提示词问题,不是 API 问题——修改后重新提交。 - 卡在运行状态 —— 为轮询设置截止时间,并将超时视为你需要处理的失败,而不是导致服务崩溃的异常。
运维问题
- 429 / 触发限流 —— 在途的提交或轮询太多。降低并发,并遵守响应中的任何重试提示。
- 提交时连接超时 —— 网络或代理问题,不是生成问题。用退避重试提交,但仅在你能够容忍可能产生重复任务时才这样做。
- 下载时视频 URL 404 —— URL 已过期。重新获取任务结果,而不是复用旧 URL。
一个可重复的习惯
每次失败都记录三个值:HTTP 状态码、响应体,以及(如果有的话)task_id。这三者能把“它坏了”变成“它在这里坏了”,而这是让调试变快的唯一关键。
接下来做什么
你现在已经掌握了完整闭环:鉴权、提交、获取任务标识符、带退避轮询,并获取结果。要投入生产,可把提交和轮询封装进一个小型客户端类,将 task_id 和提示词与每个资产一起存储以便追溯,并把轮询移到后台工作进程,让面向用户的请求永远不会因渲染而阻塞。
接下来,可以探索 HiAPI 参考文档中相邻的端点——用图生视频为现有静帧添加动画,以及提示词迭代交互方式,在投入完整生成之前打磨画面风格。你在这里学到的请求形态几乎可以原样迁移。