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