教程
如何通过 HiAPI API 使用 gemini-omni-flash/text-to-video:curl 与 Python 指南
本页内容
该端点做什么,何时使用
gemini-omni-flash/text-to-video 是 HiAPI 上的一个生成端点,可将文本提示词——可选地以首帧图像作为锚点——转换为一段短视频。你发送一个请求,HiAPI 返回一个可轮询的任务,任务完成后你会得到一个视频 URL,可下载或流式播放。
在以下场景中适合使用该端点:
- 快速概念短片。 直接根据一两句描述生成短营销预告、分镜预览或社交媒体转场素材。
- 图像引导的运动。 你已有一张静帧——产品图、角色设计、插画——希望它动起来,而不是从零开始生成。
- 流水线中的批量生成。 由于生成是异步的,你可以从后端 worker 一次性提交大量任务,之后再收集结果,而无需保持请求连接。
它不适合长视频、逐帧精确剪辑,或对特定镜头的确定性复现。可以把它看作快速的生成式初稿:迭代成本低、足以审阅、可端到端脚本化。
下面所有内容都走同一个 HiAPI 接口——一个 API key、一个基础 URL、一种请求结构——因此你在此处编写的代码无需重新学习认证或轮询,即可迁移到其他生成端点。
发送第一个请求之前
首次调用成功前,需要准备好四件事。
1. API key
在 HiAPI 账户中创建 key,并将其保存在环境变量中,而不是源代码里:
export HIAPI_API_KEY="your_key_here"
2. 基础 URL 与端点路径
所有请求都发往 HiAPI 基础 URL,模型标识符位于路径中。在代码中将基础 URL 视为单一常量,这样只需在一处修改:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. JSON 请求体
请求为 POST,带 Content-Type: application/json,并在 Authorization 头中携带 bearer token。除非你通过 URL 提供首帧图像,否则没有表单编码,也没有 multipart 上传。
4. 首帧图像(可选)
如果你打算用图像引导生成,请先确保它能通过公开 HTTPS URL 访问。本地文件系统路径不可用——API 会在服务端抓取图像。
关于成本意识的一点实用提示:该端点按你生成的输出计费——分辨率档位和片段时长都会计入。当前单价请查看 HiAPI 价格面板,因此在扩大批量任务前先在那里确认。重要的习惯是:先在最小设置下做原型,等提示词能产出想要的效果后,再调高设置。
构建生成请求
一个请求在概念上包含三部分:模型路径、提示词(以及可选的图像)和生成选项。结构如下:
{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
提示词
prompt 字段承载镜头描述。像导演笔记一样来写:主体、运镜行为、光线和氛围。具体的运动动词(“slow dolly-in”“camera pans left”“steam curls upward”)比单纯堆砌形容词更能可靠地引导结果。
可选的首帧
image 字段是可选的。省略它,模型将完全根据文本生成整个片段。包含它,片段将从该帧开始,提示词则描述接下来应发生什么。这是影响一致性最大的杠杆:纯文本提示词每次运行都会重新构想场景,而固定首帧可在多次迭代中保持构图稳定。
如果两者都提供,请确保它们一致。沙漠景观的首帧配上一段关于雨中城市街道的提示词,会产生混乱的结果——模型必须调和两个相互矛盾的指令。
选项放在哪里
resolution、duration 和 audio 与 prompt、image 一起位于同一 JSON 体的顶层。不需要记住嵌套的 options 对象。保持请求体扁平且可读——这在调试批量任务时会让日志记录和请求差异对比容易得多。
选择分辨率与时长
两个参数同时主导输出外观和任务成本:分辨率档位与片段时长。
分辨率档位
HiAPI 以多个分辨率档位公开该端点。较低档位是提示词开发阶段的合适默认值——渲染更快,让你可以迭代措辞,而不必为即将丢弃的细节付费。一旦提示词能可靠产出想要的构图,再升档做最终渲染。
一个实用的工作流:
- 在最低档位起草提示词。
- 生成两三个变体并比较。
- 锁定提示词,然后在更高档位重新渲染。
片段时长
时长以秒为单位指定,该端点围绕短片段设计。保持时长适中:短片段让单个任务更快、失败重试成本更低,并且如果以后需要更长的序列,可以再将多个片段拼接起来。如果一个镜头需要八秒屏幕时间,两次四秒生成通常比一次长生成更容易控制。
如何对应到预算
该端点按你产生的输出计费——更高分辨率和更长时长都会增加单个任务的可计费输出。由于定价按生成单位计算且档位会随时间变化,请阅读 HiAPI 价格面板上的实时数字,而不是硬编码预期。任何价格变动下都成立的规划规则:用预期任务数乘以输出规模,在最小设置下做原型,最后再扩展分辨率。
控制原生音频
audio 标志决定返回的视频是否携带与画面一起生成的原生音轨。
{
"prompt": "Rain hammering a tin roof, a door creaks open slowly",
"audio": true
}
开启时有什么变化
使用 audio: true 时,模型会生成与提示词所描述场景匹配的声音——环境音、环境质感以及动作暗示的声音事件。输出视频会附带音频流,因此你下载的文件已经完整,无需单独的音效处理。
关闭时有什么变化
使用 audio: false 时,你会得到无声视频。以下情况适合这样做:
- 你将在编辑器中为片段叠加自己的音乐或旁白。
- 该片段是更大合成作品中的背景元素。
- 你只迭代画面,不希望音频生成进入循环。
为音频编写提示词
如果启用音频,请像描述画面一样描述声景。提示词中的声音线索——雨声、脚步声、机械声、特定的房间氛围——会给音频模型提供依据。纯视觉提示词仍会产生音频,但会是通用环境音,而不是与镜头匹配的声音。
一个值得尽早测试的注意事项:音频会显著改变片段的性格。将同一提示词分别以开启和关闭标志各生成一次,观看两者,并在围绕它构建批量任务前决定项目实际需要哪种模式。
处理异步任务生命周期
视频生成耗时超过典型 HTTP 请求应保持打开的时间,因此该端点是异步的。每次调用都遵循同样的三步循环。
第 1 步:提交
将 JSON 体 POST 到端点。成功提交会立即返回一个任务标识符——通常是任务 id——以及表示任务已排队或处理中的状态。此时尚未渲染任何内容。
第 2 步:轮询
拿到任务 id,以固定间隔查询任务状态端点。每次轮询返回当前状态:queued、processing、completed 或 failed。你需要处理全部四种状态。简单的指数退避——从约两秒开始,设置间隔上限——可避免在长任务上猛打 API,同时仍能快速捕获短任务。
第 3 步:获取
当状态报告完成时,响应会携带已完成视频的 URL 以及该任务的元数据。下载它、存储它,或将 URL 交给前端。如果状态报告失败,从响应中捕获错误信息,并决定是修改提示词后重试,还是将失败暴露出来。
应内置的护栏
- 超时上限。 限制总轮询时间(例如几分钟),并在自己的代码中将任务标记为失败,而不是无限循环。
- 最大轮询次数。 防止状态始终不明确时出现失控循环。
- 持久化任务 id。 一收到就写入数据库或日志。如果进程在轮询中途崩溃,你可以恢复,而不是重新生成并支付两次费用。
- 幂等提交。 在确认第一次请求失败之前,不要因网络抖动而重新提交;重复任务会消耗真实输出。
把这个循环做对一次,它就能适用于 HiAPI 上所有异步端点。
可运行的 curl 与 Python 示例
curl:提交、轮询、获取
从环境变量设置 key 和基础 URL,然后提交:
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
响应包含任务 id。从响应中获取状态端点并轮询:
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
重复直到状态为 completed,然后从响应体取出视频 URL 并下载:
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python:同样的循环,封装起来
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"A slow dolly-in on a glass coffee cup as steam curls upward, "
"morning light, shallow depth of field",
)
print("video ready:", url)
该脚本提交一个纯文本任务,带退避地轮询,强制执行超时上限,并返回完成的 URL。传入 image_url= 可将生成锚定到首帧,或设置 audio=True 以包含原生声音。从这里开始,你可以将 generate_video 放入 worker 队列、FastAPI 路由或批量循环——该函数是自包含的,除了它创建的任务 id 外无状态。
常见失败点及规避方法
大多数失败的集成都踩中了以下五个问题之一。
提交时因参数无效被拒绝
最常见的原因是 API 无法解析请求体:缺少 prompt、时长超出支持范围,或分辨率字符串不受支持。查阅端点参考以了解可接受值,并先在本地校验。在调用前断言允许值的小工具可以节省一次往返和令人困惑的错误。
首帧图像不可访问
API 会在服务端抓取 image,因此浏览器中可用的 URL 仍可能失败——私有 bucket、会过期的签名链接和防盗链都会导致此问题。使用公开可读的 HTTPS URL,并在提交前验证它能从你的网络外部解析。
放弃轮询
同一错误的两种变体:第一次收到 processing 响应就放弃并假定失败,或轮询过于激进而触达速率限制。用上面展示的退避加上限循环同时解决两者:按计划轮询,将非终态视为正常,只在明确失败或超时时抛出异常。
丢失任务 id
如果进程在提交后、结果保存前死亡,任务已付费却无法访问。提交后立即将任务 id 写入持久存储,并在启动时检查是否仍有进行中的 id,然后再提交新任务。
规模化时输出过大
以高分辨率和长时长生成大批量会迅速放大输出量,生成的文件存储成本高、服务速度慢。小规模做原型,最终渲染一次,并保持存储生命周期规则到位。由于计费与生成输出挂钩,最便宜的修复几乎总是更小的原型迭代循环。
在预发布环境中把这份清单走一遍,你的生产路径就会顺畅。