MaxAPI ドキュメント

ベースURL一覧

3 つのホストはいずれも同じ API・ベアラーキー・エンドポイントを提供し、デフォルト動作だけが異なります：

• https://api.maxapi.dev — デフォルトのベースURL。
• https://native.maxapi.dev — 画像データを MaxAPI ホストの URL ではなくプロバイダー固有の形式（base64 / inlineData）でインライン返却します。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 では、async.maxapi.dev でも X-MaxAPI-Async: true を明示してください。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 ベース 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} — 1 つのモデルのメタデータを返します。models/ の後に返された短い ID を使用してください。

レスポンスは Google の Model および ListModelsResponse のフィールド名を使用し、name、baseModelId、version、displayName、トークン上限、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 はリクエストをキューに入れてタスク ID を返します。返された poll_url をポーリングして完了を確認します。

非同期タスク

api.maxapi.dev で async: true を指定した画像リクエストの受付は HTTP 202 です。async.maxapi.dev が画像リクエストを受け付けると、完成画像ではなくタスク id と poll_url を HTTP 200 で返します。同じ API キーでその URL をポーリングし、status が succeeded、failed、canceled のいずれかになるまで待ちます。成功時は data[].url、失敗時は error を確認してください。HTTP 200 だけで生成成功と判断しないでください。

Gemini ネイティブの非同期リクエストが受け付けられると、done: false の Operation が HTTP 200 で返ります。同じ API キーで GET /v1beta/operations/{task_id} を done: true までポーリングします。その後 error を確認し、成功時は response.candidates[].content.parts[].fileData.fileUri を読み取ります。非同期出力は inlineData ではなくホスト型の画像 URL です。

非同期タスクは完了後に画像 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 ネイティブでは、JSON 本文の asset_delivery フィールドではなく、リクエストヘッダー X-MaxAPI-Asset-Delivery: mirror でホワイトラベル CDN を選びます。これはホスト型 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 ベース URL ではありません。API 認証を不要にしたり、呼び出し元を MaxAPI から匿名化したり、リクエスト・課金記録を無効にするものではありません。生成画像 URL は共有可能なリンクとして扱い、非公開ストレージとは考えないでください。

アカウント残高

GET /v1/account/balance は、キー所有者のウォレット残高を返します。 available は現在使用可能な残高、 frozen_micro_credits は実行中の非同期タスクによって保留されます。さらに 1 クレジット = 1 USD. 同じベアラーキーで、すべてのベース 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 キーは 1 つのウォレットを共有するため、同じ残高が返されます。 このエンドポイントはアカウントのリアルタイム残高を返します。過去の利用額は、以下の 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 USD です。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"
#   }
# }

値の単位は USD です。balance は共有ウォレット残高、remaining はウォレットと月間上限の両方を適用した後にこのキーが実際に使用できる金額です。月間上限がないキーは mode が unrestricted となり、quota は省略されます。

API キー別の課金利用状況

GET /v1/account/billing/usage 共有ウォレットの現在残高と、認証に使用した 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 には 1 ページ分のリクエスト明細が入ります。料金はキーの価格倍率適用後に確定した最終金額です。

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 — ルート別の構造化された価格。