Gemini 原生格式呼叫指南

API易完整支援 Gemini 官方原生格式（/v1beta generateContent 端點）：把 base_url 指向 https://api.apiyi.com，現有 Gemini 程式碼和官方 SDK 即可無縫遷移，無需任何格式轉換。本頁基於 Google 官方文件整理（ai.google.dev/gemini-api/docs，2026年6月資料），示例均可直接複製執行。

為什麼用原生格式

OpenAI 相容格式也能調 Gemini，但以下能力只有原生格式有：

完整思考控制：thinking_level（Gemini 3 系列）/ thinking_budget（2.5 系列）、思考摘要、思維簽名
原生多模態 Part：圖片 / 音訊 / 影片直接內聯傳入，支援 media_resolution 控費 —— 見多模態與程式碼執行
程式碼執行工具：code_execution 沙箱跑 Python
精細的用量欄位：thoughts_token_count、cached_content_token_count 等

簡單文本對話、或要和其它廠商模型共用一套程式碼 → 用 OpenAI 相容模式呼叫即可。

快速開始

推薦使用 Google 官方統一 SDK google-genai（舊版 google-generative-ai 已於 2025年11月30日停止支援）：

pip install google-genai

from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",  # 你的 API易 金鑰
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="用一句話介紹你自己"
)
print(response.text)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
  httpOptions: { baseUrl: 'https://api.apiyi.com' }
});

const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: '用一句話介紹你自己'
});
console.log(response.text);

curl "https://api.apiyi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [{
      "parts": [{"text": "用一句話介紹你自己"}]
    }]
  }'

注意 base_url 是 https://api.apiyi.com（不帶 /v1），與 OpenAI 相容格式的 https://api.apiyi.com/v1 不同。請使用 API易金鑰，不是 Google AI Studio 的金鑰。

流式輸出

stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="寫一篇關於量子計算的短文"
)

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

思考控制

Gemini 是思考型模型，兩代引數不一樣，混用會直接報錯：

模型系列	引數	取值
Gemini 3 / 3.1 / 3.5	`thinking_level`	`minimal`（僅 Flash 系）/ `low` / `high`（預設）
Gemini 2.5	`thinking_budget`	token 數上限（如 0–8192），不設則模型自動控制

對 Gemini 3 系列模型同時傳 thinking_level 和 thinking_budget 會返回錯誤，只能二選一（Gemini 3 系列請用 thinking_level）。

from google.genai import types

# Gemini 3 系列：按檔位控制
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="證明根號2是無理數",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    )
)

# Gemini 2.5 系列：按 token 預算控制
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="簡單問題，要快",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=0)  # 關閉思考
    )
)

檔位選型：minimal 適合低延遲簡單任務（分類、抽取）；low 適合常規對話；high 適合複雜推理和程式碼 —— 思考 token 按輸出價計費，檔位越高賬單越貴。

思考摘要與思維簽名

思考摘要：include_thoughts=True 可在響應中返回思考過程摘要（part.thought 為 True 的 part）
思維簽名（thought signatures）：Gemini 3 引入的加密推理狀態。多輪對話（尤其函式呼叫）時要把響應裡的 thought_signature 原樣回傳，模型才能延續推理鏈。官方 SDK 自動處理，手寫 REST 請求時注意不要丟棄該欄位 —— 詳見 FC函式呼叫

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="分析這段程式碼的時間複雜度：def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2)",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high", include_thoughts=True)
    )
)

for part in response.candidates[0].content.parts:
    if getattr(part, "thought", False):
        print(f"[思考摘要] {part.text}")
    else:
        print(f"[最終答案] {part.text}")

常用配置引數

通過 config（GenerateContentConfig）傳入：

引數	說明
`system_instruction`	系統指令
`temperature`	0–2。Gemini 3 系列官方建議保持預設 1.0，調低反而可能損傷推理品質
`max_output_tokens`	最大輸出（含思考 token）
`thinking_config`	思考控制，見上文
`response_mime_type`	設為 `application/json` 強制 JSON 輸出
`response_schema`	配合 JSON 輸出的結構約束（結構化輸出）
`tools`	函式宣告 / `code_execution` 等工具
`media_resolution`	多模態輸入解析度控費，見多模態頁

用量欄位（usage_metadata）

usage = response.usage_metadata
print(f"輸入: {usage.prompt_token_count}")
print(f"輸出: {usage.candidates_token_count}")
print(f"思考: {usage.thoughts_token_count}")
print(f"快取命中: {usage.cached_content_token_count}")

欄位	說明	計費
`prompt_token_count`	輸入 tokens	按輸入價
`candidates_token_count`	輸出 tokens	按輸出價
`thoughts_token_count`	思考 tokens	按輸出價，控檔位可省
`cached_content_token_count`	快取命中 tokens	按官方折扣，見快取計費
`total_token_count`	總量	—

支援的模型與價格

模型	輸入（每 1M tokens）	輸出（每 1M tokens）	說明
`gemini-3.5-flash`	$1.50	$9.00	當前主力，多項指標反超 3.1 Pro，1M 上下文
`gemini-3.1-pro-preview`	$1.80	$10.80	Pro 旗艦
`gemini-3-pro-preview`	$1.80	$10.80	上代 Pro
`gemini-3-flash-preview`	$0.44	$2.64	輕量快速
`gemini-3.1-flash-lite`	$0.25	$1.50	超低價
`gemini-2.5-pro`	$1.25	$10.00	2.5 系 Pro
`gemini-2.5-flash`	$0.30	$2.40	2.5 系主力
`gemini-2.5-flash-lite`	$0.10	$0.40	最便宜

部分模型提供 -thinking / -nothinking 字尾別名（如 gemini-3-flash-preview-nothinking），固定開啟/關閉思考，適合不方便改請求引數的客戶端。完整列表見模型與價格總覽。

與 OpenAI 相容格式對比

特性	Gemini 原生格式	OpenAI 相容格式
base_url	`https://api.apiyi.com`	`https://api.apiyi.com/v1`
SDK	`google-genai`	`openai`
思考控制	`thinking_level` / `thinking_budget`	`reasoning_effort`
思考摘要 / 思維簽名	✅	❌
程式碼執行工具	✅	❌
媒體輸入	原生 Part 內聯（PIL / bytes）	Base64 image_url
快取命中欄位	`cached_content_token_count`	`cached_tokens`

注意事項

不支援 Files API（client.files.upload()），媒體一律內聯傳入且單檔案不超過 20MB —— 詳見多模態與程式碼執行
媒體、長上下文的緩存摺扣與命中率說明見快取計費

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

為什麼用原生格式

快速開始

流式輸出

思考控制

思考摘要與思維簽名

常用配置引數

用量欄位（usage_metadata）

支援的模型與價格

與 OpenAI 相容格式對比

注意事項

相關連結

​為什麼用原生格式

​快速開始

​流式輸出

​思考控制

​思考摘要與思維簽名

​常用配置引數

​用量欄位（usage_metadata）

​支援的模型與價格

​與 OpenAI 相容格式對比

​注意事項

​相關連結

為什麼用原生格式

快速開始

流式輸出

思考控制

思考摘要與思維簽名

常用配置引數

用量欄位（usage_metadata）

支援的模型與價格

與 OpenAI 相容格式對比

注意事項

相關連結