Gemini 3.5 Flash API 接入指南
先看結論 · Gemini 3.5 Flash 的模型 ID 是 google/gemini-3.5-flash。依下方 Gemini 原生格式發送請求,從 candidates 讀取答案、usageMetadata 讀取用量。模型權限、路由與帳戶限制,和 contents 裡的任務指令是不同層次的設定。
接入規則核對 ·
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考,不是上游即時可用性或效能報告。
接入前必讀
以下參數依據 MaxAPI 公開配置;所選路由可能另有輸入或權限要求。
- 請求模型 ID
google/gemini-3.5-flash- 輸出類型
- 語言
- Base URL
https://api.maxapi.dev- 生成方式
- Gemini 相容 generateContent
Gemini 原生請求使用含 role 與 parts 的 contents。從 candidates 讀取答案、usageMetadata 讀取用量。結構化輸出仍應由應用端驗證,不要直接信任生成文字。
模型特點與選型
穩定版入口的工程迭代流程
Google 的 Gemini 3.5 Flash 模型頁強調多步驟工作、較長任務與程式迭代,並列為穩定的文字輸出模型。這描述用途,不代表 MaxAPI 自動提供完整代理執行環境。
資料核對 ·
此模型的資料來源: Google · gemini-3.5-flash
何時值得選擇它
反覆規劃、測試、修訂且需維持穩定模型選擇時,可與 3 Flash Preview 比較。評估應包含修正輪次的完整流程,而非只看第一個答案。
限制與注意事項
Stable 是供應商發布標籤,不是 MaxAPI 可用性 SLA,也不代表它仍是 Google 最新模型。工具執行、記憶、預算及停止規則都由應用控制。
供應商能力描述的是模型本身,不等於 MaxAPI 已開通全部功能。本站接入以此入口列出的參數、輸入類型和路由為準;供應商的速度、品質定位不是服務保證。
MaxAPI 實際如何處理請求
究竟使用哪條路由?
路由優先順序為:API Key 已配置的 route_modes 列表 → 請求明確指定的路由 → 模型預設路由。Key 列表非空時,優先於請求中的 route_mode。測試特定路由前,先確認 Key 配置;只修改請求參數,不一定會切換實際使用的路由。
使用者 RPM 由旗下 Key 共同使用
使用者設定的有效 RPM 上限,由旗下 API Key 共同使用。Key 可以設得更嚴格,但 Key 上限高於使用者時,仍不能突破使用者限制。例如使用者 200 RPM,不代表每個 Key 都各有 200 RPM。全站 RPM 與並發控制仍另外生效,增加 Key 不是繞過限制的方法。
路由與價格
公開路由:official-cheap。圖片/影片 JSON 請求可指定 route_mode;Gemini 原生請求使用 X-MaxAPI-Route-Mode。路由代表接入與計費選擇,不是另一個公開模型 ID。
| 路由 | 公開基礎價格 | 計費單位 |
|---|---|---|
official-cheap | $0.9 | input · 每百萬 Token |
official-cheap | $5.4 | output · 每百萬 Token |
official-cheap | $0.09 | cache_read · 每百萬 Token |
1 積分 = 1 美元。此處為目錄基礎價格,並非帳戶即時報價;最終消耗依帳戶倍率與生效計費配置結算。Token 單價不等於每張圖片固定價格。
查看即時價格第一次呼叫
建立 MaxAPI API Key,並在服務端設定 MAXAPI_KEY,勿放入瀏覽器程式碼。Key 已設定的路由列表優先,即使請求另有指定;列表為空時才採用請求路由,都未指定則使用模型預設。API 呼叫可能產生費用。
POST /v1beta/models/gemini-3.5-flash:generateContent
curl -X POST "https://api.maxapi.dev/v1beta/models/gemini-3.5-flash:generateContent" \
-H "Authorization: Bearer $MAXAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Suggest a small test plan for an image API client. Cover a successful result, an invalid reference image and an unfinished asynchronous task. Do not invent timings or success rates."
}
]
}
]
}'第一次呼叫的驗收清單
請求合約核對 ·
依公開目錄與網關程式核對;範例只說明資料結構,不是付費模型實測、延遲測量,也不保證每條路由目前可用。
先確認請求欄位
POST /v1beta/models/gemini-3.5-flash:generateContent- URL 使用短模型 ID,本文使用 contents[].parts[].text。這是語言端點,不是圖片生成請求。
X-MaxAPI-Route-Mode- 需要明確指定路由時,使用此標頭,不要把 route_mode 塞入 Gemini 本文。API Key 已設定的路由列表仍優先於標頭。
generationConfig- 最小範例不加選填的思考、工具與輸出 Schema 參數。只加入此模型及路由支援的選項;提示詞簡短不代表固定費用。
再確認實際結果
candidates / finishReason / promptFeedback- 讀取候選文字、finishReason 與 promptFeedback;候選缺失或回答被截斷時需明確處理,HTTP 成功不等於回答可交付。
usageMetadata- 使用回傳用量與 MaxAPI 帳務記錄核對消耗。每百萬 Token 單價不等於每次回應固定價格,也不要補造缺失的 Token 數。
:streamGenerateContent- 本站目前等完整結果生成後才發送一個 SSE data 事件,提供的是格式相容,不是逐 Token 串流。請勿依此承諾即時首 Token 或設計持續打字效果。
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "Illustrative answer only."
}
]
},
"finishReason": "STOP"
}
]
}先看現象,再判斷錯誤原因
429rate_limit_exceeded / capacity_exhausted
- 如何判斷
- 429 可能來自使用者/Key RPM、全站容量,或生成容量不足。結合 Retry-After 與回傳的 X-RateLimit-*/X-Global-* 標頭判斷;單一狀態碼不能代表唯一原因。
- 下一步處理
- 有 Retry-After 時依其等待,按原因降低發送速率或同時處理數,使用有限次退避重試。全站容量不等於單一帳戶可獨占的額度。
應用場景與工作方式
下方場景與提示詞是本站建議的評估方向,不是供應商評分或實測成果。

AI 生成的概念配圖,並非此模型的實測成果或效果評測。下方提示詞供起步參考,不代表能重現配圖。
創作實踐・共通製作建議
先設計應用真正需要的答案
呼叫 Gemini 3.5 Flash 之前,先定義什麼叫做「有用的答案」。客服助手需要依提供的資料回答,資訊擷取需要穩定欄位,文案工具則可能只允許改變語氣而不能改動事實。這些不是同一種任務,應各自準備指令、範例與驗收規則,而不是把一句萬用提示詞套用到所有功能。
模型輸出應視為草稿或預測,不是執行操作的授權。結構化文字需要解析、拒絕非預期欄位,並區分缺少資訊與模型推論。如果答案會觸發訊息發送、資料寫入或交易,必須由應用另外驗證操作。建立包含正常案例與困難失敗案例的評估集,之後更换提示詞、模型或路由,才知道改善是否真實。

可以直接改寫的提示詞範例
好的提示詞是一份小型創作需求:主體是什麼、要做什麼、哪些不能改。將範例換成自己的素材與用途;尺寸、路由和品質仍應在 API 參數指定,不要只寫在文字裡。
01 / 根據已觀察的失敗測試修訂
審閱提供的任務狀態與真實測試失敗,回傳 completed_items、remaining_items、one_next_change、verification_plan。保留已驗證正確的工作,只提出能處理已證明錯誤的最小下一步,不宣稱新測試已通過,也不開始無關重構。狀態與日誌:[貼上]。生成後檢查 · 確認既有狀態被保留,提議工作仍在已觀察錯誤的範圍內。

從一次好答案到可靠功能
先寫驗收標準
選出具代表性的輸入,說明結果達到什麼程度才算可用。除了理想範例,也加入困難案例;比較期間固定請求參數,避免同時改變太多條件。
分開處理執行與呈現
保存請求識別碼與原始回應,再轉換成介面需要的格式。明確處理錯誤和不完整结果,介面逾時不應在背景悄悄觸發重複任務。
衡量可用成果,不只看呼叫成功
記錄模型、路由、輸入特徵、實際用量與審核結果。估算交付一份可用成果的成本時,也應計入人工修正與重複嘗試,而不只看單次 API 價格。

從測試到正式接入
測試實際準備使用的路由
首次比較時固定模型、路由與參數。除了常用素材,也測試大檔與特殊輸入。模型公開能力不代表每個上游渠道都能接受所有邊界情況。
區分限流與生成錯誤
遇到 429 時降低請求速率或並發,退避後再試;輸入無效應先修正素材。排查時保存請求與任務 ID,勿把 API Key 或敏感參考素材寫入公開日誌。
追蹤可用結果與實際消耗
以帳戶用量與帳務記錄確認最終結果與消耗。HTTP 成功回應可能只是任務受理,並非最終輸出。正式發布前,請檢查生成文字、視覺細節與參考素材使用權。
已核驗的接入案例
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考,不是上游即時可用性或效能報告。
多個 Key 共用使用者上限
本地回歸・通過- 驗證條件
- 使用同帳戶的兩個 Key,在記憶體測試限流器中設定較小的使用者額度。
- 實際驗證結果
- 兩個 Key 的請求消耗相同使用者額度,超出後被限流;Key 額度較大不能覆蓋使用者上限,較小的 Key 額度仍有效。
常見問題
什麼情況應選擇此模型?
反覆規劃、測試、修訂且需維持穩定模型選擇時,可與 3 Flash Preview 比較。評估應包含修正輪次的完整流程,而非只看第一個答案。
此模型入口有哪些特別需要注意的限制?
Stable 是供應商發布標籤,不是 MaxAPI 可用性 SLA,也不代表它仍是 Google 最新模型。工具執行、記憶、預算及停止規則都由應用控制。
為什麼改了 route_mode,路由卻沒變?
路由優先順序為:API Key 已配置的 route_modes 列表 → 請求明確指定的路由 → 模型預設路由。Key 列表非空時,優先於請求中的 route_mode。測試特定路由前,先確認 Key 配置;只修改請求參數,不一定會切換實際使用的路由。
每個 API Key 都有完整的使用者 RPM 額度嗎?
使用者設定的有效 RPM 上限,由旗下 API Key 共同使用。Key 可以設得更嚴格,但 Key 上限高於使用者時,仍不能突破使用者限制。例如使用者 200 RPM,不代表每個 Key 都各有 200 RPM。全站 RPM 與並發控制仍另外生效,增加 Key 不是繞過限制的方法。
這些本地回歸案例能證明線上模型效能嗎?
本地測試使用模擬請求、回應與測試儲存,不呼叫付費模型渠道。它們驗證請求處理,不驗證模型畫質、線上成功率、延遲,也不代表參考圖上限已端到端測通。頁面其他位置的概念配圖,不是這些測試的輸出。
Gemini 3.5 Flash 應填哪個模型 ID?
使用 google/gemini-3.5-flash。請依範例的端點格式傳入;Gemini 原生網址使用短模型名稱。
頁面價格適用所有帳戶和路由嗎?
1 積分 = 1 美元。此處為目錄基礎價格,並非帳戶即時報價;最終消耗依帳戶倍率與生效計費配置結算。Token 單價不等於每張圖片固定價格。
失敗請求會扣積分嗎?
MaxAPI 公開規則為失敗請求不計費。處理期間可能暫時預留餘額,請以任務最終結果與帳務記錄核對,不要將暫時餘額變動當作最終消耗。
為什麼我的 API Key 不能使用某條路由?
路由是否可用,取決於模型、帳戶權限與 API Key 允許的路由。公開列出價格不代表已取得權限;修改 route_mode 前請先確認帳戶和金鑰配置。
處理結果前應確認什麼?
Gemini 原生請求使用含 role 與 parts 的 contents。從 candidates 讀取答案、usageMetadata 讀取用量。結構化輸出仍應由應用端驗證,不要直接信任生成文字。
失敗或逾時後要立即重試嗎?
先分辨是限流、輸入錯誤,還是任務仍在執行。已有任務 ID 時,先查狀態再決定是否重新生成。僅對可重試錯誤使用有次數限制的退避重試。