Gemini Native API 兼容接口

本平台对外提供兼容 Gemini GenerateContent API 的聊天 / 文本生成接口。

本文档面向客户端调用方，重点说明公开请求路径、认证方式、请求参数和示例写法。请求体字段名与 JSON 结构尽量保持与 Gemini GenerateContent API 一致。

说明：

接口路径：
- POST /v1beta/models/{model}:generateContent
- POST /v1beta/models/{model}:streamGenerateContent
能力类型：聊天 / 文本生成
返回方式：
- generateContent：返回标准 JSON
- streamGenerateContent：返回 text/event-stream SSE 流
协议风格：请求体保持 GenerateContentRequest 原生结构，不额外包一层 input

1. 接口概览

请求方法：POST
请求路径：
- /v1beta/models/{model}:generateContent
- /v1beta/models/{model}:streamGenerateContent
Content-Type：application/json
响应类型：
- 非流式：application/json
- 流式：text/event-stream

2. 认证与请求头

请求头示例：

x-goog-api-key: YOUR_REACH_API_KEY
Content-Type: application/json

其中 Authorization 与 x-goog-api-key 至少传一个，推荐优先使用 x-goog-api-key 以保持与 Gemini 官方协议一致。

请求头说明：

请求头	必填	说明
`Authorization`	否	平台 API Key，格式：`Bearer sk-xxxxxx`
`x-goog-api-key`	否	也可直接通过该请求头传平台 API Key，兼容 Gemini 官方协议
`Content-Type`	是	固定为 `application/json`

3. 请求体

请求体保持 GenerateContentRequest 原生对象结构：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请用一句话介绍你自己。"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.2,
    "maxOutputTokens": 256
  }
}

3.1 顶层参数说明

字段	类型	必填	说明
`contents`	`array<object>`	是	对话内容列表，至少一项
`tools`	`array<object>`	否	工具或函数声明
`toolConfig`	object	否	工具调用策略配置
`safetySettings`	`array<object>`	否	安全策略覆盖
`systemInstruction`	object	否	系统提示
`generationConfig`	object	否	生成参数，例如 `temperature`、`topP`、`topK`、`maxOutputTokens`
`cachedContent`	string	否	复用缓存内容资源名

3.2 `contents.parts` 常见写法

文本输入示例：

{
  "role": "user",
  "parts": [
    {
      "text": "写一段 50 字以内的产品介绍。"
    }
  ]
}

多段输入示例：

{
  "role": "user",
  "parts": [
    {
      "text": "请总结下面的内容"
    },
    {
      "text": "第一段：......"
    }
  ]
}

4. 请求示例

4.1 标准非流式请求

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:generateContent" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请用一句话介绍 reach-api。"
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.2,
      "maxOutputTokens": 128
    }
  }'

4.2 流式请求

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请分三行介绍今天的工作重点。"
          }
        ]
      }
    ]
  }'

4.3 带函数声明的请求

curl -X POST "https://direct.reachapi.ai/v1beta/models/YOUR_MODEL_ID:generateContent" \
  -H "x-goog-api-key: YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "帮我查一下上海天气"
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_weather",
            "description": "查询指定城市天气",
            "parameters": {
              "type": "object",
              "properties": {
                "city": {
                  "type": "string"
                }
              },
              "required": ["city"]
            }
          }
        ]
      }
    ]
  }'

5. 成功响应

非流式响应示例：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "reach-api 是一个统一的 AI 网关。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "YOUR_MODEL_VERSION",
  "responseId": "resp_xxx",
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 22,
    "totalTokenCount": 40
  }
}

5.1 `usageMetadata` 说明

常见字段包括：

字段	说明
`promptTokenCount`	输入 token 数
`candidatesTokenCount`	候选输出 token 数
`totalTokenCount`	总 token 数

6. 错误响应

Gemini 风格错误示例：

{
  "error": {
    "code": 400,
    "message": "Field `contents` is required",
    "status": "INVALID_ARGUMENT"
  }
}

常见场景：

contents 缺失或为空
请求参数格式错误
鉴权失败

7. 兼容说明

路径中的 {model} 即模型 ID，请求体中不传 model
本文档列出的是常用字段和示例写法，字段名与结构以 Gemini GenerateContent API 为准
若使用 tools、toolConfig、cachedContent 等高级能力，请先确认目标模型实际支持
调用 streamGenerateContent 时，建议显式带上 ?alt=sse

8. 支持模型与参考价格

以下价格整理自统一计费文档，适用于当前已整理的 Gemini 文本模型。价格核对日期为 2026-04-17，详细口径以统一计费文档 gemini.md 为准。

模型	Input	Output	Cache read	Search grounding
`gemini-3.1-pro-preview`	`$2.00 / 1M`（`<= 200K`） / `$4.00 / 1M`（`> 200K`）	`$12.00 / 1M`（`<= 200K`） / `$18.00 / 1M`（`> 200K`）	`$0.20 / 1M`（`<= 200K`） / `$0.40 / 1M`（`> 200K`）	前 `5,000` prompts / month 免费，之后 `$14 / 1,000 search queries`
`gemini-2.5-pro`	`$1.25 / 1M`（`<= 200K`） / `$2.50 / 1M`（`> 200K`）	`$10.00 / 1M`（`<= 200K`） / `$15.00 / 1M`（`> 200K`）	`$0.125 / 1M`（`<= 200K`） / `$0.25 / 1M`（`> 200K`）	前 `1,500` RPD 免费，之后 `$35 / 1,000 grounded prompts`
`gemini-2.5-flash`	`$0.30 / 1M`	`$2.50 / 1M`	`$0.03 / 1M`	前 `1,500` RPD 免费，之后 `$35 / 1,000 grounded prompts`
`gemini-2.5-flash-lite`	`$0.10 / 1M`	`$0.40 / 1M`	`$0.01 / 1M`	前 `1,500` RPD 免费，之后 `$35 / 1,000 grounded prompts`

说明：

Gemini 部分模型按输入 token 档位区分价格，<= 200K 与 > 200K 单价不同
Search grounding 的计费单位在不同模型代际之间可能不同，详细解释见计费文档

9. 参考资料

Gemini API 参考文档： https://ai.google.dev/api/generate-content
Gemini 文本生成指南： https://ai.google.dev/gemini-api/docs/text-generation
平台统一计费文档：gemini.md

Gemini Native API 兼容接口

On this page