Gemini 原生（文字）

簡介

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（非串流）
cURL（串流）
Python
Node.js

curl -X POST "https://console.mixroute.io/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 -X POST "https://console.mixroute.io/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
    }
  }'

import google.generativeai as genai

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

model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content("用一句話介紹人工智慧")
print(response.text)

import { GoogleGenerativeAI } from "@google/generative-ai";

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

// 自訂端點
const model = genAI.getGenerativeModel(
  { model: "gemini-2.5-pro" },
  { baseUrl: "https://console.mixroute.io/v1beta" }
);

const result = await model.generateContent("用一句話介紹人工智慧");
console.log(result.response.text());

進階功能

思考模式（Thinking）

Gemini 2.5 Pro 和 Gemini 3 Pro 支援思考模式，使模型在回答前進行深度推理。Gemini 2.5 Pro - 使用 thinkingBudget：

{
  "contents": [{"role": "user", "parts": [{"text": "給一道幾何題並分步解析"}]}],
  "generationConfig": {
    "maxOutputTokens": 16384,
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 8192
    }
  }
}

Gemini 3 Pro - 使用 thinkingLevel：

{
  "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）：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        },
        {"text": "描述這張圖片的內容"}
      ]
    }
  ]
}

圖像輸入（URL）：

{
  "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）

{
  "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 搜尋（Grounding）

啟用 Google 搜尋取得即時資訊：

{
  "contents": [{"role": "user", "parts": [{"text": "今天北京天氣怎麼樣？"}]}],
  "tools": [
    {
      "googleSearch": {}
    }
  ]
}

動態檢索設定：

{
  "contents": [{"role": "user", "parts": [{"text": "最新的 AI 新聞"}]}],
  "tools": [
    {
      "googleSearch": {
        "dynamicRetrievalConfig": {
          "mode": "MODE_DYNAMIC",
          "dynamicThreshold": 0.5
        }
      }
    }
  ]
}

串流輸出

Python 串流：

import google.generativeai as genai

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

model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content(
    "寫一篇關於人工智慧的文章",
    stream=True
)

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

cURL 串流：

curl -X POST "https://console.mixroute.io/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（上下文快取）

對於長文本或多輪對話，使用快取可以節省 token 消耗。建立快取：

curl -X POST "https://console.mixroute.io/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"
  }'

使用快取：

{
  "cachedContent": "cachedContents/abc123",
  "contents": [
    {"role": "user", "parts": [{"text": "基於上述文件，總結要點"}]}
  ]
}

圖像生成

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

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "生成一張日落時分海邊的圖片"}]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"]
  }
}

Imagen 模型：

curl -X POST "https://console.mixroute.io/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

curl -X POST "https://console.mixroute.io/v1beta/models/text-embedding-004:embedContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "content": {
      "parts": [{"text": "這是一段需要向量化的文字"}]
    }
  }'

回應範例：

{
  "embedding": {
    "values": [0.0123, -0.0456, 0.0789, ...]
  }
}

批次 Embedding

curl -X POST "https://console.mixroute.io/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": "第二段文字"}]}
      }
    ]
  }'

回應範例：

{
  "embeddings": [
    {"values": [0.0123, -0.0456, ...]},
    {"values": [0.0234, -0.0567, ...]}
  ]
}

回應格式

{
  "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	伺服器內部錯誤

錯誤回應範例：

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

與 OpenAI 格式對比

特性	Gemini 原生	OpenAI 相容
Base URL	`https://console.mixroute.io/v1beta`	`https://console.mixroute.io/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`	不支援

curl --request POST \
  --url 'https://console.mixroute.io/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
    }
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "人工智慧是一門研究如何讓電腦模擬和實現人類智慧的學科。"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 20,
    "totalTokenCount": 30
  },
  "modelVersion": "gemini-2.5-pro"
}

當下熱門模型

OpenAI 官方庫使用

文本系列

文本向量系列

圖像系列

視頻系列

其他

Gemini 原生（文字）

簡介

與 OpenAI 格式的差異

API 端點

認證

請求參數

generationConfig 參數

基礎範例

進階功能

思考模式（Thinking）

多模態輸入

工具呼叫（Function Calling）

Google 搜尋（Grounding）

串流輸出

Context Caching（上下文快取）

圖像生成

Embedding API

單條 Embedding

批次 Embedding

回應格式

錯誤處理

與 OpenAI 格式對比

當下熱門模型

OpenAI 官方庫使用

文本系列

文本向量系列

圖像系列

視頻系列

其他

​簡介

​與 OpenAI 格式的差異

​API 端點

​認證

​請求參數

​generationConfig 參數

​基礎範例

​進階功能

​思考模式（Thinking）

​多模態輸入

​工具呼叫（Function Calling）

​Google 搜尋（Grounding）

​串流輸出

​Context Caching（上下文快取）

​圖像生成

​Embedding API

​單條 Embedding

​批次 Embedding

​回應格式

​錯誤處理

​與 OpenAI 格式對比

簡介

與 OpenAI 格式的差異

API 端點

認證

請求參數

generationConfig 參數

基礎範例

進階功能

思考模式（Thinking）

多模態輸入

工具呼叫（Function Calling）

Google 搜尋（Grounding）

串流輸出

Context Caching（上下文快取）

圖像生成

Embedding API

單條 Embedding

批次 Embedding

回應格式

錯誤處理

與 OpenAI 格式對比