教程
如何调用 veo-3.1 文本转视频 API:curl 与 Python 示例
面向开发者的实操集成指南
本页内容
veo-3.1/text-to-video 能为你做什么
veo-3.1/text-to-video 是通过 HiAPI 统一 API 对外提供的文本转视频生成模型。你发送一段文本提示词,选择一些输出选项,然后就会收到生成的视频。它与其他生成端点一同位于 HiAPI 上,因此如果你已经在该平台上使用图像或聊天能力,这套集成方式会让你感到熟悉:一次带认证的 HTTP 请求会返回一个任务,你通过轮询直到任务完成。
当你有一段场景的文字描述,希望生成一段短视频又不想自己管理基础设施时,这个端点就是合适的选择。你不需要自己处理 GPU 分配、模型权重或排队。代价在于生成是异步的:你提交任务,然后稍后回来查看结果。这对视频来说是常态,因为渲染所需时间超过单个请求/响应周期。
当核心输入是提示词时,就使用文本转视频。如果你之后需要图像条件或视频条件的生成,请查看模型目录中对应的端点。这里的请求结构(认证、任务提交、轮询)与你在 HiAPI 媒体端点中会复用的模式相同,所以学一次就能长期受益。你可以在 veo-3.1/text-to-video 模型页面找到完整的模型详情。
端点、认证与请求结构
所有 HiAPI 请求都使用 HTTPS 和 bearer token。请将你的 API 密钥存放在环境变量中,而不是硬编码,并把它放在 Authorization 请求头中发送:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
文本转视频请求是一个 JSON 对象,包含 model 字段和一个 input 对象。input 对象存放提示词以及任意输出控制项。最小请求体如下所示:
{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜晚穿过雨淋湿的霓虹小巷,缓慢的推拉镜头"
}
}
返回的不是最终视频,而是一个任务信封。它通常包含任务标识符、状态字段和时间戳。其结构大致如下:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-01-01T00:00:00Z"
}
字段的确切名称请以实际响应为准,但结构是一致的:你需要 id 来进行轮询,status 则告诉你任务是排队中、运行中还是已完成。不要因为提交调用返回了 200 就认为任务已完成——那只意味着任务已被接受。
选择参数:原生音频与分辨率档位
除了提示词之外,对文本转视频最重要的参数是是否生成原生音频,以及目标分辨率档位。这两者都会影响生成时间和输出性质,因此要有意识地做出选择,而不是盲目使用默认值。
原生音频
一些视频模型可以在画面之外生成音轨。如果该端点提供原生音频开关,启用它意味着生成的片段包含同步声音。这对于音频本身就是体验一部分的场景很有用——环境噪声、音乐或与动作相配的音效。如果你计划在后期添加自己的配乐或旁白,就关闭它,让输出专注于画面。音频生成也会增加处理时间,所以只在你确实需要时启用。
分辨率档位
分辨率档位让你在画面保真度与成本、延迟之间做取舍。更高档位产生更清晰的输出,但耗时更长、消耗资源更多。选择满足你交付目标的最低档位:迭代和审阅用草稿档位,最终渲染用更高档位。如果你要针对一个提示词生成许多候选,用较低档位来探索,然后以完整质量重新生成胜出的那个。计费跟随你生成的输出,因此有意识地选择档位是你可控的主要杠杆。
当你不确定该端点当前接受哪些取值时,先只带提示词发送一个请求,然后检查响应或错误信息。HiAPI 会返回结构化的校验错误,列出可接受的字段,因此你可以据此调整而无需猜测。
可运行的 curl 请求
这条 curl 命令提交一个文本转视频任务。它设置 JSON 内容类型,从环境变量传入 bearer token,并发送包含 model 和 input 的请求体。
curl -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜晚穿过雨淋湿的霓虹小巷,缓慢的推拉镜头",
"duration": 5,
"resolution": "720p"
}
}'
调用成功会返回一个包含任务 id 和 status 的 JSON 对象。记下这个 id——轮询时你需要它。如果你在写脚本,可以把输出通过 JSON 处理器提取 id:
JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-3.1/text-to-video","input":{"prompt":"夜晚穿过雨淋湿的霓虹小巷,缓慢的推拉镜头"}}' \
| jq -r '.id')
echo "$JOB_ID"
请根据实际 API 的期望调整端点路径、参数名以及任何可选字段。这套模式——POST 一个 JSON 请求体,从响应中读取 id——是后续每个示例的基础。
用 Python 发送同样的请求
Python 版本使用标准 requests 库做同样的事。从环境读取密钥,构建 payload,然后提交。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "夜晚穿过雨淋湿的霓虹小巷,缓慢的推拉镜头",
},
}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"已提交任务:{job_id}(状态:{job.get('status')})")
有两点值得强调。第一,response.raise_for_status() 会把 HTTP 错误转为异常,从而让失败立即可见,而不是让一个损坏的 payload 静默流转。第二,timeout=60 可以防止连接挂起阻塞你的脚本。提交本身很快;实际视频是异步渲染的,因此你不会在这里等待文件。接下来,你将使用 job_id 轮询完成情况。
轮询异步任务直到视频就绪
提交之后,轮询任务端点,直到状态表明完成或失败。一个带短暂休眠的简单循环开始时就很够用。
import time
while True:
res = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=headers,
timeout=30,
)
res.raise_for_status()
state = res.json().get("status")
print(f"状态:{state}")
if state == "succeeded":
video_url = res.json().get("output", {}).get("url")
print(f"视频已就绪:{video_url}")
break
if state == "failed":
raise RuntimeError(f"任务失败:{res.json()}")
time.sleep(5)
一些实用的改进:从较短的间隔开始,然后逐步退避以减少浪费的请求;增加最大尝试次数或截止时间,避免卡住的任务无限循环;并谨慎对待任何意料之外的状态,而不是假设它意味着“继续等待”。常见的状态值包括 queued、running、succeeded 和 failed。任务成功时,响应通常会携带输出 URL;请及时下载并保存文件,因为签名 URL 可能会过期。
让轮询具备幂等性,并在每次状态时记录任务 id。如果你的进程重启,可以按 id 恢复而无需重新提交。生产环境中,如果平台提供 webhook,可以考虑使用它,并以轮询作为回退。
排查常见错误
大多数失败都归入几类。请按顺序检查下面的清单,而不是盲目重试。
认证失败(401/403)
检查 Authorization 请求头是否存在且格式正确为 Bearer <key>,以及该环境变量是否确实在发起请求的 shell 或进程中设置。一个常见的陷阱是在某个 shell 中密钥存在、而在另一个 shell 中不存在的环境里运行脚本。
校验错误(400/422)
这类错误会返回关于哪个字段有误的结构化详情。常见原因:缺少 prompt、不支持的 resolution 或 duration 取值,或参数嵌套层级错误。请按字面理解错误信息——它通常会指出有问题的字段。先发送最小 payload,然后每次添加一个参数。
速率限制(429)
你发送请求太快了。实现指数退避和重试上限。如果你要启动许多任务,请错开提交时间并跟踪进行中的任务。
超时与网络错误
提交时客户端超时很少是任务本身的问题——任务在服务端运行。在提交和轮询请求上都使用合理的超时,并对幂等的 GET 请求进行重试。绝不要在未检查原任务是否已创建的情况下盲目重试 POST。
任务始终不完成
如果任务停留在 queued 或 running 的时间远超预期,请检查状态码和消息,而不是重新提交。长提示词或更高分辨率档位需要更长时间;这是正常的。如果任务报告 failed,请记录完整的响应体——错误信息通常会指出原因。
拿不准时,用尽可能最小的请求复现,并检查每一个响应。这比一次改动多个参数再猜哪个才重要要好得多。关于端点特定的细节,请参阅模型页面。