Ask

Gemini Wire API 接入说明 ​

Xima AI 支持通过 Gemini 原生 Wire API 调用 Gemini LLM 模型。和 OpenAI-compatible Chat Completions 不同，Gemini Wire API 使用 contents[].parts[] 表达输入，把系统指令、生成参数、工具调用、结构化输出、多模态输入等能力放在 Gemini 原生字段里。

如果你只是普通聊天，继续使用 快速开始 中的 OpenAI-compatible /v1/chat/completions 即可；如果需要 Gemini 原生 generateContent、streamGenerateContent、thinkingConfig、函数调用、图片内容块等能力，建议使用本文的 Wire API。

接入信息 ​

项目值
控制台https://console.xima.ai/
Base URLhttps://api-long.xima.ai
Generate Content EndpointPOST /v1/models/{model}:generateContent
Stream EndpointPOST /v1/models/{model}:streamGenerateContent?alt=sse
认证方式Authorization: Bearer <XIMA_API_KEY>

建议先配置环境变量：

bash
export XIMA_API_KEY="sk-替换为你的APIKey"
export XIMA_GEMINI_BASE_URL="https://api-long.xima.ai"
export XIMA_GEMINI_MODEL="gemini-3.8-flash"

本文示例按 Xima AI 新接入域名写认证和域名；请求体字段保持 Gemini 官方 Wire API 形态。新接入请统一使用 https://api-long.xima.ai/v1/models/...。

本文示例覆盖文本、流式、系统指令、Thinking、结构化 JSON、函数调用和图片输入。

通用示例默认使用 gemini-3.8-flash。接入 gemini-4-argon 时，请先阅读下方「Gemini 4 Argon 支持与迁移」，不要直接沿用旧模型的思考预算或采样配置。

和 Chat Completions 的差异 ​

能力OpenAI-compatibleGemini Wire API
URL/v1/chat/completions/v1/models/{model}:generateContent
模型位置body 中的 modelURL path 中的 {model}
用户输入messages[].contentcontents[].parts[]
系统指令messages[0].role = "system"system_instruction 或 SDK systemInstruction
生成参数temperature、max_tokens 等generationConfig.temperature、generationConfig.maxOutputTokens 等
工具调用tools[].functiontools[].functionDeclarations
工具调用配置tool_choicetoolConfig.functionCallingConfig
多模态输入image_url 内容块inline_data 内容块
响应文本choices[0].message.contentcandidates[0].content.parts[].text
流式输出stream: true/v1/models/{model}:streamGenerateContent?alt=sse

不要把两套协议混写。例如 Gemini Wire API 不需要在 body 里再传 model，也不要把 messages、reasoning_effort、tool_choice 直接放进 generateContent 请求体。

模型选择 ​

模型 ID建议用途
gemini-4-argon复杂推理、代码和工具调用；基础接入已验证，参数限制见下方专节
gemini-3.8-flash默认推荐；通用问答、代码、工具调用、长输出和多数生产聊天场景
gemini-3.7-flash通用生产任务、复杂摘要、代码和 Agent 场景
gemini-3.6-flash通用任务、成本和延迟更敏感的场景
gemini-3.5-flash稳定通用任务、批处理、摘要、分类
gemini-3.1-pro-preview更复杂推理、长上下文、多步骤分析
gemini-2.5-pro长上下文和复杂分析场景
gemini-2.5-flash轻量对话、低成本任务、兼容旧业务配置

模型可用状态、价格和最终计费以 模型与价格 和 Xima AI 控制台「模型与定价」页面为准。

Gemini 4 Argon 支持与迁移 ​

gemini-4-argon 已支持本文的常用接入方式。以下是 2026-10-14 在 Xima API 上的实测范围；这些能力复用已有协议，并非都需要新增字段。

能力Gemini 4 实测结果
OpenAI-compatible 普通与流式聊天已通过，返回模型为 gemini-4-argon
Gemini Wire 普通与流式文本已通过，SSE 正常返回文本和用量
thinkingLevel：low / medium / high三个级别均已通过
结构化 JSONresponse_mime_type 与 response_schema 已通过，输出可解析
函数调用函数名、参数、结果回传与最终回答闭环已通过

本次未验收图片、音视频、超长输出 continuation、长上下文或缓存命中；不要从基础文本测试推定全部高级能力已验证。

与旧模型的参数区别 ​

配置旧模型用法Gemini 4 Argon
思考强度Gemini 3 系列使用 thinkingLevel，具体可选值按模型确认只支持 low、medium、high；省略时默认为 medium
思考预算部分旧模型支持 thinkingBudget；不能跨模型直接复用不支持，单独传入也会返回 400，并非仅不能与 level 混用
minimal / 关闭思考取决于旧模型及其参数规则minimal 返回 400；不要通过预算设为 0 或旧 -nothinking 别名尝试关闭
采样参数通用示例用 temperature、topP、topK 调整采样Google 忽略这些自定义值；保留字段不代表它们有效
输出上限旧请求可能设置较小的 maxOutputTokens / max_tokens上限包含思考与最终回答，较小值可能先被思考消耗；遇到 MAX_TOKENS 应调整预算或思考级别
显式缓存部分旧模型支持，Xima 管理接口需另行确认Google 不支持显式缓存；使用隐式缓存并按实际命中量核对

迁移时先使用基础模型名 gemini-4-argon，移除 thinkingBudget / thinking_budget。不要直接沿用可能生成旧预算参数的 -thinking、-thinking-N、-nothinking 模型别名。只需要普通聊天时，现有 OpenAI-compatible 接口仍可使用。

Gemini 4 最小验证示例 ​

以下请求适合验证连接；512 只是短响应的测试上限，不是复杂任务的生产默认值。流式调用将 URL 末尾换成 :streamGenerateContent?alt=sse。

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/gemini-4-argon:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Reply with OK only."}]}],
    "generationConfig": {
      "maxOutputTokens": 512,
      "thinkingConfig": {"thinkingLevel": "low"}
    }
  }'

两种协议的思考字段位置不同：

协议实际 HTTP JSON 请求体中的位置
Gemini WiregenerationConfig.thinkingConfig.thinkingLevel
OpenAI-compatible Chat Completionsextra_body.google.thinking_config.thinking_level

OpenAI-compatible 的实际 HTTP 请求体示例（POST https://api-long.xima.ai/v1/chat/completions）：

json
{
  "model": "gemini-4-argon",
  "messages": [{"role": "user", "content": "Reply with OK only."}],
  "max_tokens": 512,
  "extra_body": {
    "google": {"thinking_config": {"thinking_level": "low"}}
  }
}

这里展示的是线上已验证的 HTTP body；SDK 的 extra_body 参数可能会执行顶层合并，使用 SDK 时需核对最终发送的 JSON 结构。不要把 OpenAI 的 extra_body 直接放进 Gemini Wire 请求。

能力选择速查 ​

需求使用位置说明
普通文本contents[].parts[].text单轮或多轮对话都使用 contents
流式输出/v1/models/{model}:streamGenerateContent?alt=sse适合聊天 UI、长文本生成和 Agent 任务
系统指令system_instruction用于设定角色、输出风格和稳定约束
采样与长度generationConfig控制输出长度；采样参数是否生效取决于模型，Gemini 4 忽略自定义采样值
ThinkinggenerationConfig.thinkingConfigGemini 3 / 4 使用 thinkingLevel；Gemini 4 不接受旧思考预算
结构化 JSONgenerationConfig.response_mime_type、response_schema适合抽取、分类、可解析输出
函数调用tools[].functionDeclarations模型只返回函数名和参数；实际执行由业务系统负责
图片输入parts[].inline_data小图片可直接 base64 传入
安全设置safetySettings覆盖指定安全类别的默认阈值
缓存统计控制台和 usageMetadata 中的缓存统计Gemini 4 仅支持隐式缓存；其他模型的显式缓存管理请先联系支持确认

本文覆盖 generateContent 和 streamGenerateContent 的常用接入方式。下方示例按常见接入顺序展开。Code execution、URL Context、Google Search grounding、大文件上传等能力如需使用，请联系 [email protected] 确认可用范围和推荐写法。显式 context cache 管理仅适用于上游支持该能力的模型，Gemini 4 不支持。

文本调用 ​

最小请求只需要 contents：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "用三句话介绍 Xima AI 的 Gemini Wire API 接入方式。"
          }
        ]
      }
    ]
  }'

成功时通常从 candidates[0].content.parts[].text 读取回答，并从响应里的 usageMetadata 或控制台日志查看 token 消耗。

多轮对话 ​

Gemini Wire API 不使用 messages。多轮对话需要把历史轮次继续放在 contents 中，角色通常是 user 和 model：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "我们要设计一个订单系统。" }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "可以先确认订单、支付、库存和履约边界。" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "请给出数据库表设计的第一版。" }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.4,
      "maxOutputTokens": 1200
    }
  }'

流式输出 ​

流式输出使用 streamGenerateContent，并加上 alt=sse：

bash
curl -N "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "写一份 300 字以内的技术方案摘要。"
          }
        ]
      }
    ]
  }'

客户端需要按 Server-Sent Events 逐段读取返回内容。不同 HTTP 客户端对缓冲策略不同，命令行调试建议使用 curl -N。

系统指令与生成参数 ​

系统指令放在 system_instruction，普通采样和输出长度控制放在 generationConfig：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {
      "parts": [
        {
          "text": "你是 Xima AI 的技术支持助手。回答要简洁、准确，优先给出可执行步骤。"
        }
      ]
    },
    "contents": [
      {
        "parts": [
          {
            "text": "用户说 API 返回 401，我应该如何排查？"
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.3,
      "topP": 0.8,
      "maxOutputTokens": 800
    }
  }'

常用生成参数（下表采样说明适用于支持这些参数的模型；Gemini 4 忽略自定义 temperature、topP、topK）：

参数说明
temperature随机性。越低越稳定，越高越发散
topPnucleus sampling 概率截断
topK候选 token 截断
maxOutputTokens最大输出 token 数
stopSequences命中后停止生成的字符串列表
candidateCount候选回答数量；生产场景通常保持 1

Thinking 配置 ​

Gemini 3 系列和 Gemini 4 Argon 可以通过 generationConfig.thinkingConfig.thinkingLevel 控制推理强度，具体可选值按模型确认。Gemini 4 支持 low、medium、high：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "请给出一个数据库慢查询排查计划，并说明每一步判断依据。"
          }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "low"
      },
      "maxOutputTokens": 1800
    }
  }'

注意事项：

项目说明
推荐值先从 low 开始；复杂推理再提高到 medium 或 high
旧模型预算thinkingBudget（部分 SDK 写作 thinking_budget）仅用于支持它的旧模型，不要与 thinkingLevel 混用
Gemini 4 限制不接受 thinkingBudget 或 minimal，单独传入也会返回 400
输出长度Gemini 4 的输出上限包含思考与回答；复杂任务不要沿用最小连接测试的输出上限
计费thinking 相关 token 通常会进入输出或额外用量统计，最终以控制台用量明细为准

结构化 JSON 输出 ​

如果业务需要稳定 JSON，不要只在 prompt 里写「请输出 JSON」。应使用结构化输出配置：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "从这句话中抽取工单信息：用户反馈支付成功但订单仍显示待支付。"
          }
        ]
      }
    ],
    "generationConfig": {
      "response_mime_type": "application/json",
      "response_schema": {
        "type": "OBJECT",
        "properties": {
          "category": {
            "type": "STRING",
            "enum": ["payment", "account", "model", "other"]
          },
          "summary": {
            "type": "STRING"
          },
          "priority": {
            "type": "STRING",
            "enum": ["low", "medium", "high"]
          }
        },
        "required": ["category", "summary", "priority"]
      }
    }
  }'

结构化输出适合信息抽取、分类、路由和 Agent 工具参数生成。业务侧仍应对返回 JSON 做解析和 schema 校验，避免把模型输出直接当成可信数据。

函数调用 ​

函数调用分四步：

  1. 在请求中定义函数名称、描述和参数 schema。
  2. 调用模型，让模型决定是否需要调用函数。
  3. 业务系统读取模型返回的函数名和参数，自己执行真实函数。
  4. 把函数结果回传给模型，让模型生成最终回答。

请求示例：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {
      "parts": [
        {
          "text": "你是订单系统助手。需要实时数据时必须调用工具。"
        }
      ]
    },
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_order_status",
            "description": "查询订单状态",
            "parameters": {
              "type": "OBJECT",
              "properties": {
                "order_id": {
                  "type": "STRING",
                  "description": "订单 ID"
                }
              },
              "required": ["order_id"]
            }
          }
        ]
      }
    ],
    "toolConfig": {
      "functionCallingConfig": {
        "mode": "ANY",
        "allowedFunctionNames": ["get_order_status"]
      }
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "帮我查一下订单 O202609100001 现在是什么状态。"
          }
        ]
      }
    ]
  }'

模型返回函数调用后，业务系统需要执行 get_order_status，再把结果放回下一轮请求。不同 SDK 对函数调用结果字段会做封装；HTTP Wire API 调试时，重点检查响应里的 functionCall 内容块，并保证下一轮传回的函数名、调用 ID 和结果能在服务端日志里对齐。

Gemini 4 的该闭环已验证。保存并回传模型返回的完整 content.parts，包括返回中可能存在的 thoughtSignature；不要只摘取函数名和参数后丢弃其他模型内容。工具结果使用对应的 functionResponse，保留可用的调用 ID。

图片输入 ​

小图片可以用 base64 内联传入：

bash
IMAGE_B64="$(base64 -i ./screenshot.png | tr -d '\n')"

curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "请识别这张截图中的主要错误信息。"
          },
          {
            "inline_data": {
              "mime_type": "image/png",
              "data": "'"$IMAGE_B64"'"
            }
          }
        ]
      }
    ]
  }'

如果图片、音频、视频或 PDF 文件较大，建议使用文件 URI 方式接入，而不是把超大的 base64 直接塞进请求体。大文件和文件 URI 接入方式请联系 [email protected] 确认。

安全设置 ​

可以通过 safetySettings 调整指定安全类别的阻断阈值：

bash
curl -sS "$XIMA_GEMINI_BASE_URL/v1/models/$XIMA_GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $XIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "safetySettings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_ONLY_HIGH"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      }
    ],
    "contents": [
      {
        "parts": [
          {
            "text": "请把这段用户反馈改写成客服工单摘要。"
          }
        ]
      }
    ]
  }'

生产环境建议保留默认安全策略，只有在明确评估业务风险和合规要求后再调整。

缓存说明 ​

Google 官方 Gemini API 有两类缓存，支持范围因模型而异：

类型说明
Implicit cachingGemini 2.5 及以上模型默认启用，用户不需要传额外参数；如果命中，响应用量中会体现缓存读取 token
Explicit caching支持该能力的模型可通过独立 cachedContents API 创建缓存，再用 cachedContent 引用；Gemini 4 不支持

Gemini 4 只支持隐式缓存，不需要创建缓存资源，也不要发送 cachedContent 引用。官方给出的隐式缓存最小输入门槛为 6,144 tokens，达到门槛并不保证命中。本次短提示测试未验证缓存命中。

生产接入建议先按 implicit caching 和 usageMetadata 做用量对账。Wire 响应关注 usageMetadata.cachedContentTokenCount，OpenAI-compatible 响应关注 usage.prompt_tokens_details.cached_tokens；缺少命中证据时，不把全部输入按缓存价格计费。其他支持显式缓存的模型如需缓存管理，请联系 [email protected] 确认当前可用范围和推荐字段。最终缓存命中和计费口径以控制台日志、用量和账单明细为准。

接入自检 ​

正式接入前，建议用 API Key 检查以下项目：

检查项判断标准
文本调用200 返回，能从 candidates[].content.parts[] 读取文本
多轮对话user、model 历史顺序正确
流式输出SSE 分块正常，客户端不会被缓冲
ThinkingthinkingConfig.thinkingLevel 不报错
结构化 JSON返回能被业务 schema 解析
函数调用模型能返回函数名和参数，工具结果闭环字段和日志对得上
图片输入base64 图片能被识别，体积限制符合预期

如果接入结果与本文示例不一致，请先检查 Base URL、模型 ID、请求字段和控制台请求日志；仍无法定位时请联系 [email protected]。

常见错误 ​

现象常见原因处理方式
401 或认证失败Key 错误、Key 未启用、认证头不是 Bearer检查 Authorization: Bearer <XIMA_API_KEY> 和控制台 Key 状态
404模型 ID 不存在或路径写错确认 URL 是 /v1/models/{model}:generateContent
400 且提示未知字段混入了 OpenAI 字段，或字段命名不符合 Gemini Wire API移除 messages、model、reasoning_effort 等 OpenAI 字段；对照控制台请求日志检查字段名
Gemini 4 报 Thinking budget is not supported传入了旧 thinkingBudget，即使未混用 level 也不支持删除预算参数，改用 thinkingLevel
Gemini 4 报 THINKING_LEVEL_MINIMAL使用了不支持的 minimal 级别使用 low、medium 或 high
其他 Thinking 参数报错模型不支持该配置，或同时传入 level 和预算按模型确认思考参数，避免混用
Gemini 4 调整 temperature 后效果不变模型忽略自定义采样参数不依赖 temperature/topP/topK 控制该模型的随机性
Gemini 4 回答为空或截断，结束原因为 MAX_TOKENS总输出上限可能先被思考消耗提高输出上限或降低思考级别，并检查用量
流式没有逐段输出客户端缓冲或缺少 alt=sse命令行用 curl -N，并确认 endpoint 是 streamGenerateContent?alt=sse
JSON 无法解析只靠 prompt 约束，未使用结构化输出配置使用 response_mime_type 和 response_schema，业务侧继续做 schema 校验

官方参考 ​