Gemini 原生協議 API 參考

    Gemini 原生協議 API 參考

    透過 Gate.AI Gemini 原生協議呼叫 Gemini 模型。適合已使用 Gemini contents\[\]、parts\[\]、tools\[\] 請求結構的應用。

    欄位值
    Base URLhttps://api.gate.ai/gemini/v1beta
    認證Authorization: Bearer <API_KEY>
    格式Gemini 原生 JSON 請求體
    文字生成POST /models/{model}:generateContent
    串流生成POST /models/{model}:streamGenerateContent?alt=sse

    Gate.AI 使用自己的 API Key，不使用 Google Gemini 的 ?key= 參數。
    Gemini 原生協議透過 URL path 中的 {model} 指定模型，例如 POST /models/gemini-2.5-pro:generateContent。請求 body 無需再次傳入 model。這與 OpenAI Chat Completions 在請求 body 中傳入 model 的方式不同。

    Base URL 等效路徑

    場景Base URL
    Gate.AI 顯式指定 Gemini 協議（推薦）https://api.gate.ai/gemini/v1beta
    Google AI Studio SDK 直接接入（去掉 /gemini 前綴）https://api.gate.ai/v1beta
    Vertex AI 風格路徑（帶前綴）https://api.gate.ai/gemini/v1/publishers/google/models/{model}:{action}
    Vertex AI 風格路徑（去前綴）https://api.gate.ai/v1/publishers/google/models/{model}:{action}

    文字生成

    POST/models/{model}:generateContent

    根據 Gemini 原生 contents\[\] 請求體生成模型回覆。

    請求參數

    名稱位置類型必填說明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是請求體格式：application/json
    modelpathstring是Gemini 模型 ID，如 gemini-2.5-pro

    請求主體

    名稱類型必填說明
    contentsarray是Gemini 對話內容，按輪次順序排列
    contents\[\].rolestring否user 或 model
    contents\[\].partsarray是一輪訊息中的內容片段
    parts\[\].textstring否文字輸入
    parts\[\].inlineDataobject否多模態輸入，包含 mimeType 和 base64 data
    toolsarray否工具宣告，使用 Gemini functionDeclarations 格式
    toolConfigobject否工具呼叫策略
    generationConfigobject否生成參數，如 temperature、maxOutputTokens
    systemInstructionobject否系統指令

    示例

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d '{7    "contents": [8      {9        "role": "user",10        "parts": [11          {"text": "Introduce Gate.AI in one sentence"}12        ]13      }14    ]15  }'

    返回欄位說明

    名稱類型說明
    candidatesarray模型候選回覆
    candidates\[\].indexinteger候選索引，從 0 開始
    candidates\[\].content.rolestring固定為 model
    candidates\[\].content.parts\[\].textstring文字回覆內容
    candidates\[\].content.parts\[\].thoughtboolean是否為模型的思考內容（reasoning）
    candidates\[\].content.parts\[\].thoughtSignaturestring思考內容簽名，用於多輪 reasoning 上下文延續
    candidates\[\].content.parts\[\].functionCallobject工具呼叫請求
    candidates\[\].finishReasonstring結束原因，如 STOP
    usageMetadataobject用量與計費資訊
    usageMetadata.promptTokenCountinteger輸入 token 數
    usageMetadata.candidatesTokenCountinteger輸出 token 數
    usageMetadata.totalTokenCountinteger總 token 數
    usageMetadata.coststring本次請求費用，單位 USD

    回傳範例

    json
    1{2  "candidates": [3    {4      "index": 0,5      "content": {6        "role": "model",7        "parts": [8          {9            "text": "Gate.AI is a unified AI model routing platform."10          }11        ]12      },13      "finishReason": "STOP"14    }15  ],16  "usageMetadata": {17    "promptTokenCount": 13,18    "candidatesTokenCount": 37,19    "totalTokenCount": 50,20    "cost": "0.0000964"21  }22}

    串流生成

    POST/models/{model}:streamGenerateContent?alt=sse

    串流返回 Gemini 回應片段。最後一段通常包含 usageMetadata。客戶端按 Gemini 串流協議讀取 candidates\[\].content.parts\[\].text 即可。

    請求參數

    名稱位置類型必填說明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是請求體格式：application/json
    modelpathstring是Gemini 模型 ID，如 gemini-2.5-pro

    請求主體

    名稱類型必填說明
    contentsarray是Gemini 對話內容，按輪次順序排列
    contents\[\].rolestring否user 或 model
    contents\[\].partsarray是一輪訊息中的內容片段
    parts\[\].textstring否文字輸入
    parts\[\].inlineDataobject否多模態輸入，包含 mimeType 和 base64 data
    toolsarray否工具宣告，使用 Gemini functionDeclarations 格式
    toolConfigobject否工具呼叫策略
    generationConfigobject否生成參數，如 temperature、maxOutputTokens
    systemInstructionobject否系統指令

    示例

    bash
    1curl -N "https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "contents": [6      {7        "role": "user",8        "parts": [9          {"text": "List three scenarios where model routing is useful"}10        ]11      }12    ]13  }'

    多模態輸入

    圖片、音訊、影片、PDF 等內容放入同一個 parts[]。Gate.AI Gemini 入口建議使用 camelCase 欄位：inlineData.mimeType。

    類型mimeType 範例
    圖片image/png、image/jpeg
    音訊audio/mp3、audio/wav
    影片video/mp4
    PDFapplication/pdf

    圖片輸入範例

    ini
    1IMAGE_B64="$(base64 -i ./image.png | tr -d '\n')"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d "{7    \"contents\": [8      {9        \"role\": \"user\",10        \"parts\": [11          {\"text\": \"描述這張圖片\"},12          {13            \"inlineData\": {14              \"mimeType\": \"image/png\",15              \"data\": \"${IMAGE_B64}\"16            }17          }18        ]19      }20    ]21  }"

    工具呼叫

    Gemini 工具使用 tools[].functionDeclarations[]。工具策略放在 toolConfig.functionCallingConfig。

    json
    1{2  "contents": [3    {4      "role": "user",5      "parts": [6        {"text": "北京今天適合穿什麼?"}7      ]8    }9  ],10  "tools": [11    {12      "functionDeclarations": [13        {14          "name": "get_weather",15          "description": "查詢城市天氣",16          "parameters": {17            "type": "object",18            "properties": {19              "city": {20                "type": "string",21                "description": "城市名"22              }23            },24            "required": ["city"]25          }26        }27      ]28    }29  ],30  "toolConfig": {31    "functionCallingConfig": {32      "mode": "AUTO"33    }34  }35}

    模型觸發工具時，會在 candidates[].content.parts[] 返回 functionCall。

    狀態碼

    狀態碼狀態碼含義說明
    200OK請求成功
    400Bad Request請求體錯誤、JSON 無效，或缺少必要的 contents / parts
    401UnauthorizedAPI Key 無效或缺失
    402Payment Required餘額不足
    404Not FoundAPI 路徑錯誤、模型不存在，或模型未啟用該協議
    413Payload Too Large多模態請求體過大
    429Too Many Requests請求過於頻繁，請降低呼叫頻率
    500Internal Server Error服務內部錯誤
    502Bad Gateway上游 Gemini 服務失敗

    和 OpenAI 相容接入的區別

    如果應用已經使用 OpenAI Chat Completions，可以繼續透過 https://api.gate.ai/openai/v1/chat/completions 呼叫 Gemini 模型。如果應用已經使用 Gemini 原生 contents\[\] / parts\[\] 格式，使用本頁的 /gemini/v1beta/models/... 端點，遷移成本更低。

    常見問題

    現象原因處理建議
    404路徑缺少 /gemini/v1beta 或模型 ID 錯誤使用 https://api.gate.ai/gemini/v1beta/models/{model}:generateContent
    多模態內容讀不到inlineData 欄位名、MIME 或 base64 不正確使用 inlineData.mimeType/data，確認 base64 不帶換行
    工具沒有觸發schema 超出 Gemini 支援的 JSON Schema 子集先使用 type、properties、required、description 等基礎欄位