HiAPI
博客

教程

如何通过 HiAPI API 调用 gemini-omni-1.1-flash:curl 与 Python 指南

2026年11月17日
抽象建筑风格封面图:暖灰混凝土平面在斜射日光下交错,带石板蓝色阴影与细窄鼠尾草色接缝。
本页内容

首次请求前需要准备什么

在写任何代码之前,先确认四件事。每一件都能帮你省下一轮调试往返。

一个 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)

这给你带来什么

  1. 换模型只需一行。 当更新的模型到来时,你改常量和默认参数;调用点不受影响。
  2. 可选参数被正确处理。 省略的值不会发送,从而避免前面描述的 null 被拒问题。
  3. 轮询对调用方不可见。 调用方要么拿到结果,要么拿到异常,绝不会拿到需要自己管理的任务 ID。
  4. 测试变得容易。 你可以分别对 post_json 和 wait_for_job 打桩,隔离测试载荷构建和轮询逻辑。

分层组织

保持结构扁平且明确:传输层(HTTP、请求头、超时、重试)、模型层(gemini-omni-1.1-flash 的载荷构建)和任务层(提交与轮询)。单个 generate_video 函数将它们组合起来,各层都足够小,出问题时便于推理。

先用 curl 确认连接配置,再转到 Python 做实际工作,参数变化时随时阅读模型页面,并把轮询循环放在接口之后,使它绝不泄漏到应用代码中。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档