教程
如何通过 HiAPI API 调用 gemini-omni-1.1-flash:curl 与 Python 指南
本页内容
首次请求前需要准备什么
在写任何代码之前,先确认四件事。每一件都能帮你省下一轮调试往返。
一个 API 密钥
对 HiAPI 的每个请求都需要用 API 密钥进行身份验证。在你的账户控制台生成一个,并确保它不进入源代码管理。下面的示例从环境变量读取它,这样密钥就不会出现在 shell 历史记录或已提交的文件中:
export HIAPI_API_KEY="your_key_here"
基础 URL 和端点路径
基础 URL 对所有 HiAPI 模型都相同;只有模型标识符会变化。端点路径和请求方法请从 API 参考文档中获取,而不是从博客文章里抄,因为路径是带版本的,可能会变动。把基础 URL 作为客户端中的一个常量,这样将来变更时只需改一行。
模型标识符
gemini-omni-1.1-flash 作为字符串在请求载荷中传入。请精确复制——连字符和版本后缀都很重要。如果拼错,错误通常是校验失败而非路由失败,这会让人困惑;请参见后面的调试章节。
收藏模型页面
gemini-omni-1.1-flash 模型页面是判断有哪些参数、接受什么取值以及响应结构如何的权威来源。把它当作每次改动前都要核对的参考,而不是读一遍就完事的东西。
这四项就绪后,你就可以发起调用了。
用 curl 发送一个最小请求
从尽可能小的请求开始。它的目的不是产出好结果——而是证明你的密钥、端点和载荷结构都对得上。一旦跑通,之后的每次改动都是增量式的。
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "镜头缓慢推近木桌上的一只陶瓷杯,柔和的晨光"
}
}'
各部分的含义如下:
- 方法与 URL —— 该调用是一个
POST,指向从 API 参考文档获取的端点路径,前面拼上你的基础 URL。 Authorization请求头 —— 携带 bearer 令牌。这里变量缺失或为空是导致 401 的最常见原因。Content-Type请求头 —— 必须为application/json。没有它,服务器可能根本不解析请求体。model—— 精确的模型标识符字符串。input—— 一个包含生成参数的对象。提示词放在这里;分辨率和时长也加在这里,详见下文。
如果调用返回的是任务标识符或已接受状态响应,而不是最终输出,那是正常的——生成是异步的。请保存好该标识符;轮询步骤会用到它。
把同样的调用移植到 Python
Python 版本应发送完全相同的 JSON 请求体。保持载荷一致才能让这次移植可信:如果 curl 成功了而 Python 没有,那问题出在你的 Python 代码里,而不是你对 API 的理解上。
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "镜头缓慢推近木桌上的一只陶瓷杯,柔和的晨光"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
有几个习惯值得立刻养成:
- 用常量构建 URL,而不是在代码各处散落字符串拼接。
- 设置显式超时。 不设置的话,卡住的请求可能让工作进程无限期挂起。
- 调用
raise_for_status(),这样错误响应会以异常形式暴露,而不是被静默当作成功响应体解析。 - 用
json.dumps序列化,不要依赖表单编码,后者无法正确生成嵌套的input对象。
跑通之后,你就有了一个可复用的请求结构。接下来两节加入真正控制输出的参数。
在请求中配置分辨率和时长
分辨率和时长是 input 对象里的普通字段,与提示词并列。概念上载荷如下:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
关键规则:不要凭记忆或几个月前读过的教程硬编码这些值。 支持的值会随模型更新而变化,传入不支持的值会产生看似载荷错误的校验错误。设置它们之前,请始终在模型页面上确认当前接受的值。
一个实用的模式
把值放在配置里,而不是代码里:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
这带来三个好处。你可以不改逻辑就调整输出质量。你可以在开发期间跑便宜的低分辨率测试,只在最终渲染时提高。当平台新增支持的值时,你只需改一个配置字段,而不用翻遍代码库。
还有两个更隐蔽的坑值得指出。第一,分辨率和时长通常与成本相关——计费通常与产出挂钩,因此更长、更高分辨率的片段不是免费的。第二,如果某字段是可选的,请省略它,而不是发送空字符串或 null;有些校验器即使字段本身可选也会拒绝显式 null。
处理异步生成:先提交,再轮询
生成需要时间,所以 API 采用先提交再轮询的模式。你的客户端必须把它们当作两个具有不同重试语义的独立操作。
第 1 步:提交
提交调用就是你已构建好的请求。它返回该任务的标识符——视端点而定,可能是任务 ID、task ID 或类似字段。防御性地解析它:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
第 2 步:轮询
然后用该标识符轮询状态端点,直到任务达到终态。一个健壮的循环具备四个特性:最大等待时间、退避、终态检查和失败检查。
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
为什么这些细节很重要
- 指数退避能避免在一个需要一分钟渲染、仍在排队的任务上不断猛打状态端点。
- 硬性截止时间防止卡住的任务永远阻塞工作进程。超时时记录任务 ID,以便手动检查。
- 显式终态意味着你绝不会在未预料到的状态上死循环。把未知状态当作“继续等待”,但记录一次日志。
- 分开的重试策略:重试提交调用比重试状态调用风险更高,因为它可能创建重复任务。可以放心重试轮询;只在明确的传输错误时重试提交。
排查常见故障模式
大多数故障归入少数几类。按这个顺序排查,因为后面的症状往往由前面的问题引起。
认证错误
症状: 401 或 403。
首先检查: 密钥是否真的存在于进程运行的环境中?打印 len(API_KEY) 能抓住变量未设置导致 bearer 令牌为空的经典情况。然后确认请求头格式是 Bearer <key>,中间只有一个空格,并且密钥未被撤销或限定到其他项目。
载荷格式错误
症状: 400,并抱怨请求体或缺少字段。
首先检查: 把你的请求体与可用的 curl 请求对比。常见原因包括缺少 Content-Type: application/json 请求头、发送表单编码数据而非 JSON、input 对象结构扁平而 API 期望嵌套(或相反),以及意外发生的类型转换——数值型 duration 以带引号的字符串发送可能校验失败。
不支持的参数值
症状: 400 或 422,并点名某个特定字段,如 resolution 或 duration。
首先检查: 模型页面,那里列出了当前支持的值。这几乎总是过时的硬编码值,而不是代码缺陷。如果一个过去可用的值现在失败,先假设模型已更新并重读文档,再假设服务故障。
模型标识符拼写错误
症状: 校验错误或未找到错误,且未提及你的提示词。
首先检查: 打印 model 字符串,并逐字符与文档对比。末尾多一个空格或版本号写反都很容易漏掉。
超时与瞬时故障
症状: 连接超时、429 或 5xx 响应。 首先检查: 你是否设置了超时。加上超时,然后只为 429 和 5xx 添加带退避的有界重试——不要重试 429 以外的 4xx 错误,因为请求每次都会以同样方式失败。对于长任务,记住最终结果是通过轮询获取的;提交调用超时并不等于生成失败。
技术上有效但结果不对
请求成功但输出不达预期。这是提示词问题,不是 API 问题。让提示词对主体、镜头运动、光照和节奏具体明确,并且每次只改一个变量,以便归因差异。
封装成可复用的客户端函数
封装的目标很简单:你的业务逻辑不应包含模型标识符、参数名或轮询循环。所有模型相关的细节都集中在一处。
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
这给你带来什么
- 换模型只需一行。 当更新的模型到来时,你改常量和默认参数;调用点不受影响。
- 可选参数被正确处理。 省略的值不会发送,从而避免前面描述的 null 被拒问题。
- 轮询对调用方不可见。 调用方要么拿到结果,要么拿到异常,绝不会拿到需要自己管理的任务 ID。
- 测试变得容易。 你可以分别对
post_json和wait_for_job打桩,隔离测试载荷构建和轮询逻辑。
分层组织
保持结构扁平且明确:传输层(HTTP、请求头、超时、重试)、模型层(gemini-omni-1.1-flash 的载荷构建)和任务层(提交与轮询)。单个 generate_video 函数将它们组合起来,各层都足够小,出问题时便于推理。
先用 curl 确认连接配置,再转到 Python 做实际工作,参数变化时随时阅读模型页面,并把轮询循环放在接口之后,使它绝不泄漏到应用代码中。