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

# Gemini 原生（文本）

> 使用 Google Gemini 原生格式调用 API

## 简介

Gemini 原生 API 采用 Google Gemini 的请求与响应格式，适用于 Google 官方客户端（如 `google-generativeai` SDK）或需要直接使用 Gemini 数据结构的场景。

若使用 OpenAI 兼容客户端（如 OpenAI SDK），请使用 `/v1/chat/completions` 接口。

### 与 OpenAI 格式的区别

| 特性   | Gemini 原生            | OpenAI 兼容                    |
| ---- | -------------------- | ---------------------------- |
| 消息结构 | `contents[].parts[]` | `messages[].content`         |
| 角色名称 | `user` / `model`     | `user` / `assistant`         |
| 流式参数 | URL 参数 `?alt=sse`    | Body 参数 `stream: true`       |
| 系统提示 | `systemInstruction`  | `messages[0].role: "system"` |
| 多模态  | `parts[]` 数组混合       | `content[]` 数组混合             |

## API 端点

| 功能           | 方法   | 路径                                                     |
| ------------ | ---- | ------------------------------------------------------ |
| 文本生成（非流式）    | POST | `/v1beta/models/{model}:generateContent`               |
| 文本生成（流式）     | POST | `/v1beta/models/{model}:streamGenerateContent?alt=sse` |
| 单条 Embedding | POST | `/v1beta/models/{model}:embedContent`                  |
| 批量 Embedding | POST | `/v1beta/models/{model}:batchEmbedContents`            |

## 认证

支持两种认证方式：

| 方式               | Header           | 示例                     |
| ---------------- | ---------------- | ---------------------- |
| Bearer Token（推荐） | `Authorization`  | `Bearer sk-xxxxxxxxxx` |
| Google 风格        | `x-goog-api-key` | `sk-xxxxxxxxxx`        |

## 请求参数

| 参数                  | 类型     | 必需 | 描述             |
| ------------------- | ------ | -- | -------------- |
| `contents`          | array  | 是  | 对话内容数组         |
| `generationConfig`  | object | 否  | 生成配置参数         |
| `safetySettings`    | array  | 否  | 安全过滤设置         |
| `systemInstruction` | object | 否  | 系统指令           |
| `tools`             | array  | 否  | 工具定义（函数调用、搜索等） |
| `cachedContent`     | string | 否  | 缓存内容名称         |

### generationConfig 参数

| 参数                | 类型      | 描述           |
| ----------------- | ------- | ------------ |
| `temperature`     | number  | 随机性（0-2）     |
| `topP`            | number  | 核采样（0-1）     |
| `topK`            | integer | Top-K 采样     |
| `maxOutputTokens` | integer | 最大输出 token 数 |
| `stopSequences`   | array   | 停止序列         |
| `candidateCount`  | integer | 候选响应数量       |
| `thinkingConfig`  | object  | 思考模式配置       |

## 基础示例

<Tabs>
  <Tab title="cURL（非流式）">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "contents": [
          {"role": "user", "parts": [{"text": "用一句话介绍人工智能"}]}
        ],
        "generationConfig": {
          "temperature": 0.7,
          "maxOutputTokens": 1024
        }
      }'
    ```
  </Tab>

  <Tab title="cURL（流式）">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "contents": [
          {"role": "user", "parts": [{"text": "写一首关于春天的诗"}]}
        ],
        "generationConfig": {
          "temperature": 0.8,
          "maxOutputTokens": 2048
        }
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import google.generativeai as genai

    genai.configure(
        api_key="sk-xxxxxxxxxx",
        transport="rest",
        client_options={"api_endpoint": "https://api.mixroute.ai"}
    )

    model = genai.GenerativeModel("gemini-2.5-pro")
    response = model.generate_content("用一句话介绍人工智能")
    print(response.text)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    import { GoogleGenerativeAI } from "@google/generative-ai";

    const genAI = new GoogleGenerativeAI("sk-xxxxxxxxxx");

    // 自定义端点
    const model = genAI.getGenerativeModel(
      { model: "gemini-2.5-pro" },
      { baseUrl: "https://api.mixroute.ai/v1beta" }
    );

    const result = await model.generateContent("用一句话介绍人工智能");
    console.log(result.response.text());
    ```
  </Tab>
</Tabs>

## 高级功能

<Tabs>
  <Tab title="思考模式">
    ### 思考模式（Thinking）

    Gemini 2.5 Pro 和 Gemini 3 Pro 支持思考模式，使模型在回答前进行深度推理。

    **Gemini 2.5 Pro** - 使用 `thinkingBudget`：

    ```json theme={null}
    {
      "contents": [{"role": "user", "parts": [{"text": "给一道几何题并分步解析"}]}],
      "generationConfig": {
        "maxOutputTokens": 16384,
        "thinkingConfig": {
          "includeThoughts": true,
          "thinkingBudget": 8192
        }
      }
    }
    ```

    **Gemini 3 Pro** - 使用 `thinkingLevel`：

    ```json theme={null}
    {
      "contents": [{"role": "user", "parts": [{"text": "解释量子纠缠的原理"}]}],
      "generationConfig": {
        "maxOutputTokens": 16384,
        "thinkingConfig": {
          "includeThoughts": true,
          "thinkingLevel": "MEDIUM"
        }
      }
    }
    ```

    | 参数               | 适用模型           | 可选值                       |
    | ---------------- | -------------- | ------------------------- |
    | `thinkingBudget` | Gemini 2.5 Pro | 1-24576（token 数量）         |
    | `thinkingLevel`  | Gemini 3 Pro   | `LOW` / `MEDIUM` / `HIGH` |
  </Tab>

  <Tab title="多模态输入">
    ### 多模态输入

    支持图像、音频、视频等多种输入格式。

    **图像输入（Base64）：**

    ```json theme={null}
    {
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "inlineData": {
                "mimeType": "image/jpeg",
                "data": "BASE64_ENCODED_IMAGE"
              }
            },
            {"text": "描述这张图片的内容"}
          ]
        }
      ]
    }
    ```

    **图像输入（URL）：**

    ```json theme={null}
    {
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "fileData": {
                "mimeType": "image/jpeg",
                "fileUri": "https://example.com/image.jpg"
              }
            },
            {"text": "这张图片里有什么？"}
          ]
        }
      ]
    }
    ```

    **支持的 MIME 类型：**

    * 图像：`image/jpeg`, `image/png`, `image/gif`, `image/webp`
    * 音频：`audio/mp3`, `audio/wav`, `audio/aac`
    * 视频：`video/mp4`, `video/webm`
    * 文档：`application/pdf`
  </Tab>

  <Tab title="工具调用">
    ### 工具调用（Function Calling）

    ```json theme={null}
    {
      "contents": [{"role": "user", "parts": [{"text": "上海今天天气怎么样？"}]}],
      "tools": [
        {
          "functionDeclarations": [
            {
              "name": "get_weather",
              "description": "获取指定城市的天气信息",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "城市名称"
                  },
                  "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位"
                  }
                },
                "required": ["location"]
              }
            }
          ]
        }
      ],
      "toolConfig": {
        "functionCallingConfig": {
          "mode": "AUTO"
        }
      }
    }
    ```

    **工具调用模式：**

    * `AUTO`：模型自动决定是否调用
    * `ANY`：强制调用工具
    * `NONE`：禁止调用工具
  </Tab>

  <Tab title="Google 搜索">
    ### Google 搜索（Grounding）

    启用 Google 搜索获取实时信息：

    ```json theme={null}
    {
      "contents": [{"role": "user", "parts": [{"text": "今天北京天气怎么样？"}]}],
      "tools": [
        {
          "googleSearch": {}
        }
      ]
    }
    ```

    **动态检索配置：**

    ```json theme={null}
    {
      "contents": [{"role": "user", "parts": [{"text": "最新的 AI 新闻"}]}],
      "tools": [
        {
          "googleSearch": {
            "dynamicRetrievalConfig": {
              "mode": "MODE_DYNAMIC",
              "dynamicThreshold": 0.5
            }
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="流式输出">
    ### 流式输出

    **Python 流式：**

    ```python theme={null}
    import google.generativeai as genai

    genai.configure(
        api_key="sk-xxxxxxxxxx",
        transport="rest",
        client_options={"api_endpoint": "https://api.mixroute.ai"}
    )

    model = genai.GenerativeModel("gemini-2.5-pro")
    response = model.generate_content(
        "写一篇关于人工智能的文章",
        stream=True
    )

    for chunk in response:
        print(chunk.text, end="", flush=True)
    ```

    **cURL 流式：**

    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "contents": [{"role": "user", "parts": [{"text": "讲一个故事"}]}]
      }'
    ```
  </Tab>

  <Tab title="Context Caching">
    ### Context Caching（上下文缓存）

    对于长文本或多轮对话，使用缓存可以节省 token 消耗。

    **创建缓存：**

    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1beta/cachedContents" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "models/gemini-2.5-pro",
        "displayName": "my-cache",
        "contents": [
          {
            "role": "user",
            "parts": [{"text": "这是一段很长的文档内容..."}]
          }
        ],
        "ttl": "3600s"
      }'
    ```

    **使用缓存：**

    ```json theme={null}
    {
      "cachedContent": "cachedContents/abc123",
      "contents": [
        {"role": "user", "parts": [{"text": "基于上述文档，总结要点"}]}
      ]
    }
    ```
  </Tab>

  <Tab title="图像生成">
    ### 图像生成

    使用 Gemini 2.0 Flash 或 Imagen 模型生成图像：

    ```json theme={null}
    {
      "contents": [
        {
          "role": "user",
          "parts": [{"text": "生成一张日落时分海边的图片"}]
        }
      ],
      "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"]
      }
    }
    ```

    **Imagen 模型：**

    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1beta/models/imagen-3.0-generate-002:predict" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "instances": [
          {"prompt": "一只可爱的猫咪在阳光下"}
        ],
        "parameters": {
          "sampleCount": 1
        }
      }'
    ```
  </Tab>
</Tabs>

## Embedding API

### 单条 Embedding

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1beta/models/text-embedding-004:embedContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "content": {
      "parts": [{"text": "这是一段需要向量化的文本"}]
    }
  }'
```

**响应示例：**

```json theme={null}
{
  "embedding": {
    "values": [0.0123, -0.0456, 0.0789, ...]
  }
}
```

### 批量 Embedding

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1beta/models/text-embedding-004:batchEmbedContents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "requests": [
      {
        "model": "models/text-embedding-004",
        "content": {"parts": [{"text": "第一段文本"}]}
      },
      {
        "model": "models/text-embedding-004",
        "content": {"parts": [{"text": "第二段文本"}]}
      }
    ]
  }'
```

**响应示例：**

```json theme={null}
{
  "embeddings": [
    {"values": [0.0123, -0.0456, ...]},
    {"values": [0.0234, -0.0567, ...]}
  ]
}
```

## 响应格式

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "回复文本"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 20,
    "totalTokenCount": 30
  }
}
```

## 错误处理

| HTTP 状态码 | 错误类型                | 描述          |
| -------- | ------------------- | ----------- |
| 400      | INVALID\_ARGUMENT   | 请求参数无效      |
| 401      | UNAUTHENTICATED     | API 密钥无效或缺失 |
| 403      | PERMISSION\_DENIED  | 无权访问该模型     |
| 404      | NOT\_FOUND          | 模型不存在       |
| 429      | RESOURCE\_EXHAUSTED | 超出速率限制      |
| 500      | INTERNAL            | 服务器内部错误     |

**错误响应示例：**

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid value at 'contents[0].parts[0]'",
    "status": "INVALID_ARGUMENT"
  }
}
```

## 与 OpenAI 格式对比

| 特性       | Gemini 原生                        | OpenAI 兼容                    |
| -------- | -------------------------------- | ---------------------------- |
| Base URL | `https://api.mixroute.ai/v1beta` | `https://api.mixroute.ai/v1` |
| 消息结构     | `contents[].parts[]`             | `messages[].content`         |
| 角色名称     | `user` / `model`                 | `user` / `assistant`         |
| 系统提示     | `systemInstruction`              | `messages[0].role: "system"` |
| 流式请求     | URL 参数 `?alt=sse`                | Body 参数 `stream: true`       |
| 温度范围     | 0-2                              | 0-2                          |
| 工具调用     | `tools[].functionDeclarations`   | `tools[].function`           |
| 搜索增强     | `tools[].googleSearch`           | 不支持                          |
| 思考模式     | `thinkingConfig`                 | 不支持                          |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent' \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "contents": [
        {"role": "user", "parts": [{"text": "用一句话介绍人工智能"}]}
      ],
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 1024
      }
    }'
  ```

  ```python Python theme={null}
  import google.generativeai as genai

  genai.configure(
      api_key="sk-xxxxxxxxxx",
      transport="rest",
      client_options={"api_endpoint": "https://api.mixroute.ai"}
  )

  model = genai.GenerativeModel("gemini-2.5-pro")
  response = model.generate_content("用一句话介绍人工智能")
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  import { GoogleGenerativeAI } from "@google/generative-ai";

  const genAI = new GoogleGenerativeAI("sk-xxxxxxxxxx");
  const model = genAI.getGenerativeModel(
    { model: "gemini-2.5-pro" },
    { baseUrl: "https://api.mixroute.ai/v1beta" }
  );

  const result = await model.generateContent("用一句话介绍人工智能");
  console.log(result.response.text());
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'contents' => [
              ['role' => 'user', 'parts' => [['text' => '用一句话介绍人工智能']]]
          ],
          'generationConfig' => [
              'temperature' => 0.7,
              'maxOutputTokens' => 1024
          ]
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "contents": []map[string]interface{}{
              {"role": "user", "parts": []map[string]string{{"text": "用一句话介绍人工智能"}}},
          },
          "generationConfig": map[string]interface{}{
              "temperature": 0.7,
              "maxOutputTokens": 1024,
          },
      }
      body, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
          "contents": [{"role": "user", "parts": [{"text": "用一句话介绍人工智能"}]}],
          "generationConfig": {"temperature": 0.7, "maxOutputTokens": 1024}
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1beta/models/gemini-2.5-pro:generateContent')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request.body = {
    contents: [{ role: 'user', parts: [{ text: '用一句话介绍人工智能' }] }],
    generationConfig: { temperature: 0.7, maxOutputTokens: 1024 }
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "candidates": [
      {
        "content": {
          "parts": [{"text": "人工智能是一门研究如何让计算机模拟和实现人类智能的学科。"}],
          "role": "model"
        },
        "finishReason": "STOP",
        "index": 0,
        "safetyRatings": []
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 10,
      "candidatesTokenCount": 20,
      "totalTokenCount": 30
    },
    "modelVersion": "gemini-2.5-pro"
  }
  ```
</ResponseExample>