博客

教程

HiAPI 上的 Gemini-4 Argon 与 Carbon:curl、Python 与可运行请求

一份实用集成指南,面向在 gemini-4-argon、gemini-4-carbon 和 gemini-4-carbon@vertex 之间做选择的开发者

2026年11月17日
HiAPI 教程文章的扁平深靛蓝色封面图,图中嵌套的宽V形箭头带有杏色前缘,沿对角线向上层叠。
本页内容

写代码之前先选定 Gemini-4 变体

任何 Gemini-4 集成的第一个决定不是 curl 还是 Python——而是你发送哪个模型 ID。在 HiAPI 上,gemini-4-argon、gemini-4-carbon 和 gemini-4-carbon@vertex 是三个不同的可路由目标,你在 model 字段中传入的字符串决定了由哪个后端来服务你的请求。提前选定它,可以省去调试一个本就无法工作的请求体的麻烦。

实践中的三个目标

  • gemini-4-argon —— 一个独立的 Gemini-4 变体,拥有自己的模型 ID。把它当作它自己的模型,而不是别名:它的行为、延迟特征和输出特性可能与 Carbon 不同。
  • gemini-4-carbon —— HiAPI 标准路由下的默认 Carbon 目标。
  • gemini-4-carbon@vertex —— 同一 Carbon 系列,但通过由 Vertex 支持的路由提供服务。@vertex 后缀是模型 ID 本身的一部分,而不是一个单独的参数。

如何决定

从工作负载出发。如果你在广泛评估 Gemini-4,请对 gemini-4-argon 和 gemini-4-carbon 分别运行相同的提示词,并在定下来之前比较输出。如果你确实需要 Vertex 路由——比如因为它与你团队已经在运营的环境相匹配——那就直接以 gemini-4-carbon@vertex 为目标。

实际要点:这三个都使用相同的请求结构。选择变体只是改一行的事,因此你可以等到拥有一个可运行的请求之后再确定最终决定。如果你想先看模型卡片,请参见 gemini-4-argon 和 gemini-4-carbon。

本指南中的示例全程使用 gemini-4-carbon;要跟随任何变体操作,只需替换该 ID。

准备好凭据和基础 URL

在任何请求体变得重要之前,必须先确保三件事正确:基础 URL、API 密钥和鉴权头格式。大多数首次请求失败都出在这三者之一。

你需要什么

  1. 一个 API 密钥,来自你的 HiAPI 账户仪表板。把它当作机密——从环境变量加载,而不是粘贴到源文件中。
  2. HiAPI 基础 URL。 所有模型调用都发往同一主机;模型变体由 model 字段选择,而不是由路径选择。
  3. 每个请求都要带两个头:
    • Authorization: Bearer $HIAPI_API_KEY
    • Content-Type: application/json

设置你的环境

export HIAPI_API_KEY="your-key-here"

然后在写任何代码之前,验证你的 shell 能看到它:

echo "${HIAPI_API_KEY:0:4}..."

如果它没有打印任何内容,说明你的密钥未在当前 shell 中导出,每个请求都会因鉴权错误而失败。在这里修复它,而不是在你的客户端里修。

你将反复使用的请求结构

下面的每个示例都发送一个 JSON 请求体,其中包含一个 model 字符串和一个 messages 数组。这种结构在 curl 与 Python 之间、非流式与流式之间、以及模型变体之间都不会改变。保持它稳定,你就可以通过复制请求体来移植代码。

一个可运行的 curl 请求

下面是一个完整、可直接复制粘贴的非流式调用。在添加任何其他内容之前先运行它——这里请求通过就证明你的密钥、基础 URL 和请求头都正确。

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an idempotency key is in two sentences."}
    ]
  }'

每个字段的作用

  • model —— 变体选择器。把它改成 gemini-4-argon 或 gemini-4-carbon@vertex,无需其他任何改动即可命中不同目标。
  • messages —— 一个有序数组。角色有 system、user 和 assistant。如果你使用系统消息,请把它放在最前面。
  • content —— 消息文本。对于简单的文本轮次,它是一个普通字符串。

阅读响应体

响应是一个 JSON 对象,包含模型的回复以及诸如 token 用量之类的元数据。由于这是非流式,整个请求体一次性到达,curl 在打印后退出。如果你得到一个可解析的 JSON 对象并带有消息回复,你的请求就是通的——后续所有内容都建立在这个基线之上。

一个快速的健全性检查:把输出通过 JSON 格式化器(| jq .)处理,这样响应结构就清晰可读,而不是一行长文本。

用 Python 发送同样的请求

Python 版本保持请求体完全一致——只有传输方式改变。使用 requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gemini-4-carbon",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what an idempotency key is in two sentences."},
    ],
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

为什么这与 curl 调用完全对应

注意,payload 与上一节的 JSON 请求体逐字节相同。json= 参数会把它序列化并为你设置 Content-Type;请求头字典提供鉴权。模型、消息或角色都没有变化。

两个值得保持的习惯

  • 设置超时。 没有超时的话,连接一旦停滞就会让你的进程无限挂起。对于非流式调用,timeout=60 是一个合理的起点。
  • 在读取响应体之前调用 raise_for_status()。 失败的请求返回结构化错误对象,而不是补全结果——在 4xx 上检查 json() 会误导你。先让异常抛出,然后记录响应文本。

把请求体放在一个函数或小型配置对象中,这样流式和工具调用部分就能扩展它,而不是复制它。

为调用添加流式支持

先让非流式请求通过。然后再启用流式——失败模式不同,同时叠加两种改动会让错误变得难以区分。

开启流式

在现有请求体中添加一个字段:

{
  "model": "gemini-4-carbon",
  "stream": true,
  "messages": [
    {"role": "user", "content": "List three uses for a message queue."}
  ]
}

这就是协议的全部改动。服务器现在会返回一串事件,而不是一个 JSON 文档。

正确地消费流

关键规则:不要在流式响应上调用 .json()。 你会遇到解析错误,因为响应体不是一个单独的 JSON 对象。使用 requests 时,逐行迭代并分别解析每个分块:

import json, os, requests

response = requests.post(
    f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gemini-4-carbon",
        "stream": True,
        "messages": [{"role": "user", "content": "List three uses for a message queue."}],
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if decoded.startswith("data: "):
        decoded = decoded[len("data: "):]
    if decoded.strip() == "[DONE]":
        break
    try:
        chunk = json.loads(decoded)
    except json.JSONDecodeError:
        continue
    print(chunk)

需要注意什么

  • 向 requests 传入 stream=True。 否则客户端会先缓冲整个响应体,之后你才看到一行内容,这就违背了初衷。
  • 跳过空行和非 JSON 的保活消息。 上面的 try/except 是刻意为之——流中可能包含不可解析为分块的行。
  • 跨分块累积文本。 每个分块携带的是片段,不是完整回复。在文本增量到达时追加它们。

流式可用之后,在你的非流式测试中把 stream 改回 false,这样工具调用保持易于阅读。要了解 Carbon 目标的概览,gemini-4-carbon 模型页面 是一个不错的参考点。

为请求体添加工具调用

工具调用在两处改变请求:你声明工具,并且你要处理一个可能包含工具调用请求而非文本的响应轮次。只有在非流式文本调用通过之后才添加此功能。

声明工具

在 model 和 messages 旁边添加一个 tools 数组。每个工具有一个名称、一个描述,以及其参数的 JSON Schema。描述很重要——它是模型用来判断是否调用该工具的依据。

{
  "model": "gemini-4-carbon",
  "messages": [
    {"role": "user", "content": "What is the weather in Lisbon?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

工具调用循环

使用工具的请求是一段对话,而不是单次调用:

  1. 发送用户消息以及工具声明。
  2. 检查助手轮次。如果它包含工具调用参数,说明模型想让你运行某些东西。
  3. 执行本地函数——HiAPI 不会运行你的代码。
  4. 追加两条消息:助手的工具调用轮次,以及一条带有函数结果、与匹配调用 ID 关联的 tool 角色消息。
  5. 重新发送完整消息历史。模型现在产出最终答案。

工具特有的失败点

  • Schema 不匹配。 如果你的 parameters schema 将某个字段标记为必需,但结果中省略了它,后续轮次可能会被拒绝。保持 schema 精确。
  • 丢弃历史。 每次重新发送都必须包含原始用户消息和工具调用轮次——而不仅仅是工具结果。
  • 流式加工具。 工具调用参数可能被拆分到多个流分块中到达。在你学习流程期间,用 stream: false 运行工具,这样每个轮次都以一个可读对象到达。

无需重写客户端即可切换模型和提供方

因为模型变体只是请求体中的一个字符串,切换目标属于配置变更,而不是重构。将客户端设计成从变量读取模型 ID——环境变量、配置文件、CLI 标志——绝不要在多个地方硬编码。

切换本身

export HIAPI_MODEL="gemini-4-carbon"      # default
export HIAPI_MODEL="gemini-4-argon"       # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex"  # Vertex-backed Carbon

在代码中,在请求体里引用该变量:

payload = {
    "model": os.environ["HIAPI_MODEL"],
    "messages": messages,
}

@vertex 后缀随模型字符串一起传递。不要把它拆成单独字段或去掉——它是可路由 ID 的一部分,去掉它会静默地把你路由到非 Vertex 目标。

切换后需要重新测试什么

  1. 纯文本轮次 —— 确认 ID 被识别且鉴权仍然有效。
  2. 你最长的真实提示词 —— 不同变体处理长输入或结构化输入的方式可能不同;验证截断和格式。
  3. 流式 —— 重新运行流式路径,因为分块节奏和边界可能因目标而异。
  4. 工具调用 —— 重新验证完整的工具调用循环;参数格式是变体差异最常暴露的地方。

保留一个小型冒烟测试脚本,针对当前设置的 HIAPI_MODEL 运行这四项检查。这样切换提供方就变成了配置变更加一条命令,而不是一次调试会话。

排查常见的请求失败

几乎每个集成失败都可归入少数几类。匹配症状、应用修复,并在改动其他任何东西之前重新运行非流式基线。

鉴权与路由

  • 401 或 403。 密钥缺失、过期或前缀不正确。检查请求头是否恰好是 Authorization: Bearer <key>,中间只有一个空格,并确认该变量确实已在运行代码的 shell 或进程中导出。打印前几个字符以确认。
  • 端点返回 404。 你的基础 URL 错误或路径段重复。模型放在请求体里,而不是 URL 里。
  • 模型未找到。 模型 ID 有拼写错误。逐字符对照 gemini-4-argon、gemini-4-carbon 和 gemini-4-carbon@vertex——@vertex 后缀是人们最常漏掉的。

请求体问题

  • 400 并带有 schema 消息。 通常是 messages 格式错误:缺少 role、content 本应是字符串却不是,或数组为空。从本指南中最小的两行请求体开始,一次添加一个字段。
  • 添加工具后返回 400。 你的 parameters schema 是无效的 JSON Schema,或者工具结果轮次与助手消息中的调用 ID 不匹配。记录完整响应体——错误文本会指出有问题的字段。

流式失败

  • 响应上的 JSON 解析错误。 你在对流调用 .json()。改为逐行迭代并解析每个分块,并跳过空行和 [DONE] 标记。
  • 响应一次性到达。 你忘了在客户端调用中设置 stream=True,所以 requests 缓冲了整个响应体。
  • 输出被截断。 你的循环提前中断——通常是在空行或保活消息上。只在显式的流结束标记处停止。

调试纪律

按照你构建时的相同顺序进行二分排查:鉴权和请求头,然后非流式文本,然后流式,然后工具。每一层都有不同的失败特征,所以你最后改的东西几乎总是原因。每次失败时记录 HTTP 状态和完整响应体——消息通常会指出具体字段。

先让基线在 gemini-4-argon 或 gemini-4-carbon 上通过,然后从那里扩展请求体。如果你仍在决定哪个变体适合你的工作负载,gemini-4-argon 模型页面 是入手之处。

立即开始构建持久 AI 产物

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

阅读 API 文档