> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/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 | 思考模式設定 |

## 基礎範例

**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
    }
  }'
```

**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
    }
  }'
```

**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)
```

**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());
```

## 進階功能

**思考模式**

### 思考模式（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` |

**多模態輸入**

### 多模態輸入

支援圖像、音訊、影片等多種輸入格式。

**圖像輸入（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`

**工具呼叫**

### 工具呼叫（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`：禁止呼叫工具

**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
        }
      }
    }
  ]
}
```

**串流輸出**

### 串流輸出

**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": "講一個故事"}]}]
  }'
```

**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": "基於上述文件，總結要點"}]}
  ]
}
```

**圖像生成**

### 圖像生成

使用 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
    }
  }'
```

## 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` | 不支援 |

```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
```

```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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.