> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 原生格式

> 基于生产环境复核，使用 Gemini 3 Pro 的原生 API 能力

> 更新日期：2026-06-06

# Gemini 原生格式

本文页只写入 `2026-03-22` 已在 Crazyrouter 生产环境复核过的 Gemini Native 用法。

当前主示例模型：

* `gemini-3.1-pro`

已按成功请求经验单独整理的多模态页面：

* [Gemini 图片理解](/chat/gemini/vision)
* [Gemini 视频理解](/chat/gemini/video)
* [Gemini 音频理解](/chat/gemini/audio)

## 端点

```text theme={null}
POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent
```

## 认证

通过 URL 参数传入 API Key：

```text theme={null}
?key=YOUR_API_KEY
```

***

## 基本文本生成

```bash cURL theme={null}
curl "https://api.crazyrouter.com/v1beta/models/gemini-3.1-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Explain machine learning in one sentence."
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 128
    }
  }'
```

当前生产返回的关键结构：

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "...",
            "thoughtSignature": "..."
          }
        ]
      }
    }
  ]
}
```

***

## 流式生成

本轮已复核 `streamGenerateContent` 可以通过 SSE 返回增量内容。

```bash cURL theme={null}
curl "https://api.crazyrouter.com/v1beta/models/gemini-3.1-pro:streamGenerateContent?key=YOUR_API_KEY&alt=sse" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Write one short sentence about AI."
          }
        ]
      }
    ]
  }'
```

当前生产收到的 SSE 片段形态类似：

```text theme={null}
data: {"candidates":[{"content":{"parts":[{"text":"...","thoughtSignature":"..."}]}}]}
```

***

## 结构化输出

当前生产已复核 `responseMimeType + responseSchema` 可用：

```bash cURL theme={null}
curl "https://api.crazyrouter.com/v1beta/models/gemini-3.1-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Return a JSON object with keys city and country for Tokyo."
          }
        ]
      }
    ],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "country": {"type": "string"}
        },
        "required": ["city", "country"]
      }
    }
  }'
```

当前生产验证返回：

```json theme={null}
{"city":"Tokyo","country":"Japan"}
```

***

## Google Search

当前生产已复核 `googleSearch` 工具可用：

```bash cURL theme={null}
curl "https://api.crazyrouter.com/v1beta/models/gemini-3.1-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Use Google Search to find one recent headline from a major technology news site."
          }
        ]
      }
    ],
    "tools": [
      {
        "googleSearch": {}
      }
    ]
  }'
```

当前生产返回的关键字段包括：

* `groundingMetadata.webSearchQueries`
* `groundingMetadata.groundingChunks`
* `groundingMetadata.groundingSupports`

***

## Thinking

当前生产已复核 `thinkingConfig` 可用：

```bash cURL theme={null}
curl "https://api.crazyrouter.com/v1beta/models/gemini-3.1-pro:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Which is larger, 9.11 or 9.9? Explain briefly."
          }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingBudget": 256
      },
      "maxOutputTokens": 512
    }
  }'
```

当前生产验证的关键标志：

```json theme={null}
{
  "usageMetadata": {
    "thoughtsTokenCount": 120
  }
}
```

***

## generationConfig 常用字段

| 字段                 | 类型      | 说明              |
| ------------------ | ------- | --------------- |
| `maxOutputTokens`  | integer | 最大输出 Token 数    |
| `temperature`      | number  | 采样温度            |
| `responseMimeType` | string  | 结构化输出时的 MIME 类型 |
| `responseSchema`   | object  | 结构化输出约束         |
| `thinkingConfig`   | object  | 思考模式配置          |

<Note>
  Gemini Native 使用 `contents[].parts[]` 结构，而不是 OpenAI 的 `messages` 结构。如果你想走 OpenAI 风格，请改用 [Gemini OpenAI 兼容格式](/chat/gemini/openai-compat)。
</Note>

相关页面：

* [模型官方定价方式](/reference/official-pricing-methods)