MaxAPI ドキュメント

開発者ガイド：Python、Node.js、非同期タスク、エラー対処

MaxAPI は共通の API エンドポイントを通じて画像・動画・言語モデルを提供します。Authorization ヘッダーの Bearer トークンで認証します。 1 クレジット = 1 USD. 失敗したリクエストは課金されません。各公開モデルは、リクエストごとに価格が変わる 1 つ以上の route_mode ティアを提供します。

ベースURL一覧

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

https://api.maxapi.dev — デフォルトのベースURL。
https://native.maxapi.dev — 画像データを MaxAPI ホストの URL ではなくプロバイダー固有の形式（base64 / inlineData）でインライン返却します。Gemini の :generateContent の返却形式と一致します。
https://async.maxapi.dev — 生成リクエストはデフォルトで非同期になり（ポーリング用のタスク id を返す）、async:true を渡す必要がありません。

エンドポイントファミリー

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 | pro | x | a. JSON ボディ、または次のヘッダーで指定します: X-MaxAPI-Route-Mode （Gemini ネイティブの場合）。
これらは認識されるルート値であり、すべてのモデルが全ルートに対応することを保証するものではありません。利用可否はモデル、有効なルート、アカウントによって異なります。pro・x・a にはアカウント権限が必要で、権限なしで指定すると 403 が返されます。
ルートの優先順位：API キーに route_modes リストが設定されている場合、そのリストがリクエストの指定より優先されます。未設定ならリクエストで明示したルート、どちらも未設定ならモデルの既定ルートが使われます。料金を比較する前に API キーの設定を確認してください。
asset_delivery: default または mirror. mirror は返される URL をエイリアス CDN ドメインに書き換えます。
async: true はリクエストをキューに入れてタスク ID を返します。返された poll_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
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 3.5 Flash — google/gemini-3.5-flash
Seedance 2.0 Fast — model/seedance-2.0-fast
Seedance 2.0 — model/seedance-2.0
Seedance 2.5 — model/seedance-2.5

機械可読インデックス

/llms.txt — プラットフォームの概要。
/docs/llms.txt — ドキュメント向けのプレーンテキスト。
/models.json — 構造化されたモデルカタログ。
/pricing.json — ルート別の構造化された価格。