MaxAPI 文件

Base URL 一覽

三個主機提供完全相同的 API、Bearer 金鑰與端點，差別只在預設行為：

• https://api.maxapi.dev — 預設的 Base URL。
• https://native.maxapi.dev — 以供應商原生格式（base64 / inlineData）內嵌回傳影像位元組，而非 MaxAPI 託管的 URL；與 Gemini 的 :generateContent 回傳格式一致。
• https://async.maxapi.dev — POST /v1/images/generations 與 POST /v1/images/edits 使用 https://async.maxapi.dev 時，省略 async 即預設非同步；明確傳入 async: false 則使用同步。在 https://api.maxapi.dev 上請傳入 async: true 啟用非同步。這項主機預設不會啟用 Gemini 原生接口的非同步模式。

支援的 Gemini 原生圖片請求 /v1beta/models/{model}:generateContent 必須明確傳入 X-MaxAPI-Async: true，即使使用 async.maxapi.dev 也一樣。請使用 generationConfig.responseModalities: ["IMAGE"]，圖生圖時明確指定 imageConfig.aspectRatio。使用非同步無法保留的原生功能時，必須改用同步；不要同時設定非同步與 X-MaxAPI-Inline-Data: true。

Gemini Interactions API

POST /v1beta/interactions · GET /v1beta/interactions/{id} · DELETE /v1beta/interactions/{id}

支援文字、圖片、SSE 串流與已儲存對話延續；可用模型及功能依路由而異。

端點家族

• OpenAI 相容: GET /v1/models, POST /v1/images/generations, POST /v1/images/edits, POST /v1/videos/generations, GET /v1/images/generations/{task_id}, GET /v1/videos/generations/{task_id}.
• Gemini 原生（語言與圖片）: POST /v1beta/models/{model}:generateContent, GET /v1beta/models, GET /v1beta/models/{model}, GET /v1beta/operations/{task_id}.
• OpenAI 文字 / 嵌入: /v1/chat/completions, /v1/responses, /v1/embeddings (中繼提供；預設不含公開模型種子).
• 帳戶: GET /v1/account/balance, GET /v1/account/billing/usage, GET /api/usage/token, GET /v1/usage. 餘額相容端點支援 OpenAI 風格工具、new-api 與 sub2api。

認證

在每個請求送出 Authorization: Bearer $MAXAPI_KEY 。Gemini 原生端點另外也接受 x-goog-api-key 以及 ?key=.

OpenAI 模型查詢

使用 OpenAI 相容的 models API，列出此 API 金鑰可用的所有模型。回應同時包含帶供應商前綴的標準 ID，以及可明確解析的短別名。

curl -s "https://api.maxapi.dev/v1/models" \
  -H "Authorization: Bearer $MAXAPI_KEY"

回應使用 OpenAI 的清單格式：object 為 list，data 包含具有 id、object 與 owned_by 的模型物件。目前此端點不提供 OpenAI 格式的單一模型查詢。

Gemini 模型查詢

使用 Google 官方 models API 格式，列出此 API 金鑰可用的 Gemini 原生模型。相同端點可在所有 MaxAPI Base URL 使用；Gemini SDK 建議使用 native.maxapi.dev。

# List available Gemini models
curl -s "https://native.maxapi.dev/v1beta/models?pageSize=50" \
  -H "x-goog-api-key: $MAXAPI_KEY"

# Get one model
curl -s "https://native.maxapi.dev/v1beta/models/gemini-2.5-flash" \
  -H "x-goog-api-key: $MAXAPI_KEY"

• GET /v1beta/models — 列出可用的 Gemini 模型。pageSize 預設為 50、上限為 1000；若要繼續查詢，請將 nextPageToken 作為 pageToken 傳回。
• GET /v1beta/models/{model} — 回傳單一模型的中繼資料。請使用 models/ 後方回傳的短 ID。

回應使用 Google 的 Model 與 ListModelsResponse 欄位名稱，包括 name、baseModelId、version、displayName、Token 上限、supportedGenerationMethods 與 nextPageToken。

MaxAPI 結構化模型目錄

當你需要文件與產品中繼資料，而不是 SDK 相容回應時，請使用 MaxAPI 的公開 JSON 目錄。

curl -s "https://www.maxapi.dev/models.json"

不需要 API 金鑰。此目錄包含 public_model_id、display_name、kind、route_modes、文件連結、支援選項、圖片與價格摘要。它是公開文件目錄，不會依特定 API 金鑰篩選；請使用 /v1/models 或 /v1beta/models 查詢該金鑰可用的模型。

常用請求參數

• route_mode: official | official-cheap | mix. 放在 JSON 主體中，或作為 X-MaxAPI-Route-Mode （用於 Gemini 原生）。

  這些是可辨識的路由值，不代表每個模型都支援全部路由。實際可用性取決於模型、已啟用路由及帳戶。

  路由優先順序：若 API 金鑰已設定 route_modes 清單，該清單優先於請求中的指定。若未設定，則使用請求明確指定的路由；兩者皆未設定時，使用模型預設路由。比較路由價格前，請先確認 API 金鑰設定。

• asset_delivery: default 或 mirror. 圖片 URL 與白標 CDN
• async: true 會將請求排入佇列並回傳 task id；輪詢回傳的 poll_url 以取得完成結果。

非同步任務

api.maxapi.dev 接受帶有 async: true 的圖片請求後回傳 HTTP 202。async.maxapi.dev 接受圖片請求後，以 HTTP 200 回傳任務 id 與 poll_url，並非已生成的圖片。請使用同一把 API 金鑰輪詢該 URL，直到 status 為 succeeded、failed 或 canceled。成功時讀取 data[].url，失敗時查看 error；不要僅憑 HTTP 200 判定生成成功。

Gemini 原生非同步請求被接受後，以 HTTP 200 回傳 done: false 的 Operation。使用同一把 API 金鑰輪詢 GET /v1beta/operations/{task_id}，直到 done: true。接著檢查 error；成功時讀取 response.candidates[].content.parts[].fileData.fileUri。非同步輸出為託管圖片 URL，不是 inlineData。

非同步任務完成後本來就會回傳圖片 URL，不需要額外的 response_format 參數。請在提交任務時設定 CDN 交付選項：該選項會隨任務保存並套用到結果 URL；只在輪詢時加入參數，不會改變該任務的交付設定。

圖片 URL 與白標 CDN

託管圖片 URL 的 default 使用 https://cdn.maxapi.dev，mirror 使用白標網域 https://cdn.dshsdh.space。呼叫 /v1/images/generations 與 /v1/images/edits 時，在 JSON 提交 "asset_delivery": "mirror"，或在 multipart 表單提交 asset_delivery=mirror。

curl https://async.maxapi.dev/v1/images/generations \
  -H "Authorization: Bearer $MAXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-pro-image-preview",
    "prompt": "A clean product photo of a glass cube",
    "resolution": "1K",
    "asset_delivery": "mirror"
  }'

Gemini 原生請求請用標頭 X-MaxAPI-Asset-Delivery: mirror 選擇白標 CDN，不要在 JSON 本文加入 asset_delivery。這只決定託管 fileData URL 的網域，不會把 inlineData 改成 URL。同步請求若要取得 URL，請另外設定 X-MaxAPI-Inline-Data: false。

curl https://async.maxapi.dev/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "Authorization: Bearer $MAXAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "X-MaxAPI-Async: true" \
  -H "X-MaxAPI-Asset-Delivery: mirror" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "A clean product photo of a glass cube"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"imageSize": "1K", "aspectRatio": "1:1"}
    }
  }'

default → https://cdn.maxapi.dev/generated/...
mirror → https://cdn.dshsdh.space/generated/...

白標交付只替換素材 URL 的網域，不會更換 API Base URL，也不代表免鑑權、向 MaxAPI 隱藏呼叫者身分，或不記錄請求與消費。生成圖片 URL 應視為可分享的連結，而非私人儲存空間。

帳戶餘額

GET /v1/account/balance 會回傳金鑰擁有者的錢包餘額。 available 是目前可用的餘額， frozen_micro_credits 是被進行中的非同步任務凍結的，且 1 積分 = 1 美元. 使用相同的 bearer 金鑰，於所有 base URL 皆可用。

請使用您要查詢其帳戶餘額的 API 金鑰進行驗證。

curl -s https://native.maxapi.dev/v1/account/balance \
  -H "Authorization: Bearer $MAXAPI_KEY"

# {
#   "object": "credit_balance",
#   "available": 34.25608,
#   "available_micro_credits": 34256080,
#   "frozen_micro_credits": 0,
#   "total_micro_credits": 34256080,
#   "available_usd": 34.25608,
#   "usd_per_credit": 1,
#   "status": "active"
# }

• available: 目前可使用的積分。
• frozen_micro_credits: 由執行中的非同步任務預留的積分。
• total_micro_credits: 可用積分與預留積分的總和。
• available_usd: 以美元顯示的可用餘額。
• status: 錢包狀態。

同一帳戶下的多個 API 金鑰共用一個錢包，因此會回傳相同餘額。 此端點回報帳戶的即時餘額。歷史消費請使用下方依 API 金鑰區分的帳單端點。

OpenAI 風格的餘額工具可直接從以下讀取： GET /dashboard/billing/subscription (餘額位於 hard_limit_usd) 以及 GET /dashboard/billing/usage. usage 相容端點不會回傳依 API 金鑰區分的歷史用量。

new-api 餘額相容

GET /api/usage/token 實作 QuantumNous/new-api 使用的 API 金鑰額度回應。請使用要查詢的 API 金鑰認證；每把金鑰只能查詢自身資料。

curl -s https://native.maxapi.dev/api/usage/token \
  -H "Authorization: Bearer $MAXAPI_KEY"

# {
#   "code": true,
#   "message": "ok",
#   "data": {
#     "object": "token_usage",
#     "name": "Production",
#     "total_granted": 50000000,
#     "total_used": 12500000,
#     "total_available": 37500000,
#     "unlimited_quota": false,
#     "model_limits": {"gpt-image-2": true},
#     "model_limits_enabled": true,
#     "expires_at": 0
#   }
# }

quota 欄位使用 new-api 的預設整數單位：500,000 quota 等於 1 美元。total_used 是此金鑰在目前 UTC 月已結算的用量；total_available 是共享可用錢包與此金鑰月度剩餘額度中的較小值。

sub2api 餘額相容

GET /v1/usage 實作 Wei-Shaw/sub2api 使用的 API 金鑰餘額回應。接受 Authorization: Bearer、x-api-key 或 x-goog-api-key；不接受查詢字串中的 API 金鑰。

curl -s https://native.maxapi.dev/v1/usage \
  -H "x-api-key: $MAXAPI_KEY"

# {
#   "mode": "quota_limited",
#   "isValid": true,
#   "status": "active",
#   "remaining": 75,
#   "unit": "USD",
#   "balance": 80,
#   "quota": {
#     "limit": 100,
#     "used": 25,
#     "remaining": 75,
#     "unit": "USD"
#   }
# }

數值單位為美元。balance 是共享錢包金額；remaining 是同時套用錢包與月度上限後，此金鑰實際可使用的金額。沒有月度上限的金鑰會回傳 unrestricted 模式並省略 quota。

依 API 金鑰查詢帳單用量

GET /v1/account/billing/usage 回傳共用錢包的目前餘額，以及僅限本次 Bearer API 金鑰的歷史用量。 呼叫者無法指定或檢視其他金鑰。

curl -s "https://native.maxapi.dev/v1/account/billing/usage?from=2026-08-01T00%3A00%3A00Z&to=2026-09-01T00%3A00%3A00Z&limit=100" \
  -H "Authorization: Bearer $MAXAPI_KEY"

預設回傳目前 UTC 月初至今的資料。可使用 RFC3339 格式的 from（包含）與 to（不包含）、limit（1–500），以及回傳的 cursor 查詢較舊明細。

summary 與模型彙總涵蓋整個查詢期間，data 則包含一頁請求明細。費用是套用該金鑰價格倍率後的最終結算金額。

同一帳戶的所有金鑰共用 balance。monthly_quota 表示此金鑰在目前 UTC 月份的額度上限、已用量與剩餘額度；無上限金鑰的 limit 與 remaining 回傳 null。

各模型 API 參考

• GPT Image 2 — openai/gpt-image-2
• GPT Image 2.5 Sunburst — openai/gpt-image-2.5-sunburst
• GPT Image 2.5 Flare — openai/gpt-image-2.5-flare
• Gemini 2.5 Flash Image — google/gemini-2.5-flash-image
• Gemini 3.1 Flash Lite Image — google/gemini-3.1-flash-lite-image
• Nanobanana Pro — google/gemini-3-pro-image-preview
• Gemini 3.1 Flash Image Preview — google/gemini-3.1-flash-image-preview
• Nano Banana 2.1 — google/gemini-nano-banana-2.1
• Gemini 3 Pro Image Preview Beta — google/gemini-3-pro-image-preview-beta
• Gemini 3.1 Flash Image Preview Beta — google/gemini-3.1-flash-image-preview-beta
• GPT Image 2 Beta — openai/gpt-image-2-beta
• Gemini 2.5 Flash — google/gemini-2.5-flash
• Gemini 2.5 Flash-Lite — google/gemini-2.5-flash-lite
• Gemini 2.5 Pro — google/gemini-2.5-pro
• Gemini 3 Flash Preview — google/gemini-3-flash-preview
• Gemini 3.1 Flash-Lite — google/gemini-3.1-flash-lite
• Gemini 3.1 Pro Preview — google/gemini-3.1-pro-preview
• Gemini 4 Argon — google/gemini-4-argon
• Gemini 3.8 Flash — google/gemini-3.8-flash
• Gemini 3.5 Flash — google/gemini-3.5-flash
• Seedance 2.0 Fast — bytedance/seedance-2.0-fast
• Seedance 2.0 Mini — bytedance/seedance-2.0-mini
• Seedance 2.0 — bytedance/seedance-2.0
• Seedance 2.5 — bytedance/seedance-2.5
• Z-Image Turbo — prunaai/z-image-turbo
• Qwen Image Edit 2511 — qwen/qwen-image-edit-2511
• Wan 2.2 I2V Fast — wan-video/wan-2.2-i2v-fast
• Seedream 4.0 — bytedance/seedream-4.0
• Seedream 4.5 — bytedance/seedream-4.5
• Seedream 5.0 — bytedance/seedream-5.0
• Seedream 5.0 Pro — bytedance/seedream-5.0-pro
• Seedream 5.0 Lite — bytedance/seedream-5.0-lite

機器可讀索引

• /llms.txt — 平台高階摘要。
• /docs/llms.txt — 以文件為主的純文字。
• /models.json — 結構化模型目錄。
• /pricing.json — 結構化的各路由定價。