教程
如何通过 HiAPI API 使用 gemini-omni-flash 生成视频
文生视频与图生视频的请求路径、模型选择,以及一份可用的集成检查清单
本页内容
为什么 gemini-omni-flash 有两个视频端点
在写第一行代码之前,最重要的决定是:你实际需要两个视频端点中的哪一个。gemini-omni-flash 在 HiAPI 上以两个独立模型的形式提供,而不是一个带模式标志的端点:
gemini-omni-flash/text-to-video—— 仅根据文本提示词生成视频。gemini-omni-flash/image-to-video—— 以提供的源图像作为视觉锚点,并在文本提示词引导下生成视频。
之所以拆分,是因为这两个任务的输入不同、校验规则不同、失败模式也不同。文生视频只需要校验一个提示词字符串。图生视频还必须抓取并解码你的源图像,因此多了一类文本路径上根本不会出现的错误(URL 不可达、格式不受支持、资源过大)。
经验法则:如果你已经有一张静态图像——产品图、分镜帧、照片——就用图生视频,因为模型会从你的视觉内容出发,而不是凭空创造。如果你只有一个想法、没有任何参考素材,就用文生视频。
从第一天起就在代码库中把这两个模型 ID 区分开。把它们当作一个“视频”概念、之后再补一个 if has_image 标志,正是集成最终出现混乱负载和难以理解 bug 的原因。
哪些保持不变
两个端点共用相同的认证方案、相同的基础 URL、相同的一般请求/响应约定,以及相同的计费模式(视频按生成的输出计费,而不是按请求次数计费)。正是这些共用的部分让单一请求构建器成为可行方案——后文详述。
哪些不同
只有负载结构和输入校验不同。差异小到足以让你在不重复整套集成代码的情况下同时支持两个端点。
前置条件与 API 设置
首次调用前,你需要三样东西。
1. API 密钥
在 HiAPI 账户中创建密钥,并将其存为环境变量,而不是硬编码:
export HIAPI_API_KEY="your_key_here"
每个请求都通过 Authorization 头中的 bearer token 进行认证。没有单独的签名步骤,也没有每次请求的 nonce。
2. 基础 URL 与模型命名约定
所有调用都发往同一个 HiAPI 基础 URL,模型由请求体中的 model 字段选择。模型 ID 遵循 family/variant 模式,因此视频模型写作 gemini-omni-flash/text-to-video 和 gemini-omni-flash/image-to-video。你只需改一个字符串来切换端点,而不是更换主机。
3. 发起请求的工具
curl 足以验证连通性,Python(配合 requests)足以构建真正的集成。两者都不需要厂商专用 SDK——该 API 就是 HTTPS 上的普通 JSON。
连通性检查
在生成任何视频之前,先访问一个轻量端点(例如列出可用模型),确认密钥可用、网络路径正常。如果那一步就失败,你调试的是凭据或连通性,而不是视频生成——搞清楚是哪一种能省下大量时间。
快速检查清单:
- 密钥已在将运行请求的 shell 中导出。
- 基础 URL 已记录并在各处一致使用(脚本之间不要出现结尾斜杠漂移)。
- 每个 POST 都设置了
Content-Type: application/json。 - 有办法在不截断的情况下查看原始 JSON 响应。
发起文生视频请求
从尽可能最小的、有机会成功的请求开始。不要一上来就填满所有可选参数——如果最小请求失败,你就知道问题是结构性的;如果成功,之后每加一个参数都是可单独归因的变更。
最小结构
文生视频请求发送模型 ID 和提示词:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,湿沥青上的反光,电影感"
}
这就是完整的负载。发送它,确认收到成功的响应对象,然后才开始丰富内容。
逐步演进请求
最小调用成功后,一次添加一个参数,并在每次添加后重新验证。文本路径上典型的追加项:
- 提示词细节 —— 主体、运动、镜头行为、光照和氛围。含糊的提示词产生含糊的运动;描述什么在动、镜头如何运动。
- 时长 / 输出长度 —— 视频按生成的输出计费,所以长度直接影响成本。明确固定它,而不是依赖你尚未核实的默认值。
- 宽高比或分辨率(如果模型支持),以匹配下游播放器或社交媒体格式。
真正重要的提示词写作要点
文生视频的质量主要由提示词的具体程度决定。三个好习惯:
- 描述运动,而不只是内容。“一只纸船顺排水沟漂下”给了模型可动画的东西;“一只纸船”没有。
- 说明镜头。固定、平移、推进、手持——镜头语言能消除大量歧义。
- 限定在一个场景。在单个短片中描述多镜头,往往产生糊成一团的结果。
当文生视频结果不佳时,先改提示词,再动任何技术参数。
发起图生视频请求
图像路径在结构上与文本路径相同,只多了一样:源图像。你学到的“最小优先”测试方法在这里同样适用。
最小结构
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "轻柔的手持漂移,主体略微转向镜头,柔和的窗光",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
此时提示词描述的是相对于图像的运动和镜头行为,而不是场景内容——图像已经提供了内容。这是最常见的概念性错误:人们写完整的场景描述,然后纳闷为什么输出忽略了他们的源帧。
如何提供源图像
图像作为引用传递,服务必须能够抓取它。有两个实际后果:
- 资源必须可被服务公开访问,不能位于你的 localhost、VPN 或带认证的存储桶之后。短期过期的签名 URL 可以,只要请求执行时它仍然有效。
- 格式和大小必须受支持。坚持使用常见 Web 格式和合理尺寸。40 MB 的 TIFF 就是在等着一场调试。
如果你的图像存放在私有存储中,在请求时生成短期签名 URL,而不是试图把存储桶设为公开。
与文本路径的实际差异
- 提示词的角色从描述场景变为描述运动。
- 校验多了一个资源抓取步骤,因此出现了一整类新的失败(见调试章节)。
- 输出构图受源图像宽高比约束,这会影响你规划下游布局。
先在浏览器中测试图像 URL。如果它对你也无法干净加载,对服务也一样。
用 curl 和 Python 调用 API
让同一个请求在两个地方都能工作:终端(用于快速迭代和原始可见性)和你的代码库(用于实际使用)。
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,电影感"
}'
把 model 字符串换成 gemini-omni-flash/image-to-video 并加上 image 字段,即可命中另一个端点——其他都不用改。
使用 -sS,这样错误不会被悄悄吞掉;检查响应时用 JSON 格式化工具管道处理,让嵌套字段可读。
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,电影感",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
两个值得照抄的细节:从环境变量读取密钥,并设置足够宽松的超时。视频生成不是即时请求——10 秒的默认超时会产生虚假失败,看起来像 API 错误,其实只是你的客户端提前放弃。
对于图生视频,加一行:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
在遇到非 2xx 状态码时,抛出异常前务必打印或记录原始响应体。错误文本通常会直接指名有问题的字段。
组织你的集成代码
两条路径各自跑通后,你很容易想在代码库里留下两个几乎相同的函数。稍微更好的结构几乎不花成本,而且在你添加第二个视频模型的那一刻就会回本。
两个共享组件
一个请求构建器。一个接收意图级参数并返回负载字典的函数:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
端点选择变成了“我有没有图像?”的结果,这与实际产品决策一致。调用方永远不直接接触模型 ID。
一个响应处理器。一个把传输错误、负载错误和模型级失败分开处理,并返回规范化结果对象(状态、视频引用、用于日志的原始响应体)的函数。所有调用方都经过它,因此两个端点的错误语义保持一致。
为什么这样做值得
- 模型 ID 只需改一处。当你迁移到不同的视频模型时,只需编辑构建器,而不是十五个调用点。
- 一致的错误处理。图像抓取失败和提示词校验失败以相同方式呈现到你的 UI。
- 无需网络即可测试。构建器是纯函数;你可以低成本地单元测试负载结构。
- 计费可见性。由于视频按生成的输出计费,单一处理器是记录时长和输出大小以跟踪成本的天然位置。
让构建器保持轻薄。关于生成什么的业务逻辑属于调用方;构建器只需知道如何以 API 的形状表达该意图。
调试常见请求失败
几乎所有早期失败都落入三类之一。先确定类别,再修复。
类别 1:请求结构
症状:立即返回 4xx、错误消息提到缺失或未知字段,或抱怨 JSON 格式错误。
按顺序检查:
- JSON 有效吗?把请求体粘贴到 linter 中。手动编辑负载留下的一个尾随逗号是经典问题。
- 模型 ID 完全一致吗?
gemini-omni-flash/text-to-video与gemini-omni-flash-text-to-video不是同一个字符串。这里的拼写错误会产生读起来像认证问题的“模型未找到”错误。 - 请求头完整吗?
Authorization和Content-Type: application/json都已设置。 - 模型与端点匹配吗?把
image字段发到文本端点不会得到你想要的结果——该字段要么被拒绝,要么被忽略,无论哪种你都会得到错误结果。
类别 2:输入资源(仅图像路径)
症状:请求被接受,但在处理过程中失败,或者错误提到抓取或解码图像。
检查:
- 在没有 cookie 的隐私浏览器窗口中打开图像 URL。如果它加载不了,服务也加载不了。
- 确认 URL 不是 localhost 地址、私有网络主机或已过期的签名链接。
- 确认格式是常见 Web 格式,文件大小合理。
- 确认响应确实是图像——返回 200 状态码但内容是 HTML 错误页的 CDN 是出奇常见的陷阱。
类别 3:模型调用本身
症状:请求有效、资源可达,但生成失败或被拒绝——通常与内容政策或容量有关。
检查:
- 缩减到最小提示词并重试。如果成功,你的提示词就是变量。
- 检查客户端超时是否足够长——在日志中,客户端超时看起来和服务器失败一模一样,除非你检查是否收到过响应。
- 启用完整的请求/响应日志(密钥脱敏),这样你能一眼区分这三类问题。
有效的调试顺序
最小负载 → 验证 → 添加图像 → 验证 → 逐个添加可选参数 → 验证。出问题时,你最后做的改动就是元凶。只要坚持一次只调试一个变量,大多数集成痛苦都会消失。
从每个端点的最小可用调用开始,用共享构建器和处理器包装它,然后逐步扩展——这条路径能让你在集成增长时,文生视频和图生视频都保持可预测。