MaxAPI documentation

Base URLs

All three hosts serve the same API, bearer key, and endpoints — they differ only in defaults:

• https://api.maxapi.dev — the default base URL.
• https://native.maxapi.dev — returns image bytes inline in the provider-native format (base64 / inlineData) instead of MaxAPI-hosted URLs; matches what Gemini's :generateContent returns.
• https://async.maxapi.dev — For POST /v1/images/generations and POST /v1/images/edits, https://async.maxapi.dev defaults to asynchronous processing when async is omitted; async: false explicitly requests synchronous processing. On https://api.maxapi.dev, send async: true to request asynchronous processing. This host default does not enable Gemini-native async requests.

For supported Gemini-native image requests to /v1beta/models/{model}:generateContent, explicitly send X-MaxAPI-Async: true, even on async.maxapi.dev. Use generationConfig.responseModalities: ["IMAGE"] and set imageConfig.aspectRatio explicitly for edits. Requests using native features that cannot be preserved asynchronously must be sent synchronously; do not combine async with X-MaxAPI-Inline-Data: true.

Gemini Interactions API

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

Text, images, SSE streaming and stored conversation continuations. Model and feature availability depends on the route.

Endpoint families

• OpenAI-compatible: 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-native (language and image): POST /v1beta/models/{model}:generateContent, GET /v1beta/models, GET /v1beta/models/{model}, GET /v1beta/operations/{task_id}.
• OpenAI text/embeddings: /v1/chat/completions, /v1/responses, /v1/embeddings (relayed; no public model seeds by default).
• Account: GET /v1/account/balance, GET /v1/account/billing/usage, GET /api/usage/token, GET /v1/usage. Balance compatibility endpoints support OpenAI-style tools, new-api, and sub2api.

Authentication

Send Authorization: Bearer $MAXAPI_KEY on every request. Gemini-native endpoints additionally accept x-goog-api-key and ?key=.

OpenAI model discovery

List all models available to your API key using the OpenAI-compatible models API. Canonical provider-prefixed IDs and unambiguous short aliases are both returned.

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

The response uses OpenAI's list shape: object is list, and data contains model objects with id, object, and owned_by. This endpoint does not currently provide an OpenAI-style single-model lookup.

Gemini model discovery

List the Gemini-native models available to your API key using Google's official models API shape. The same endpoint works on every MaxAPI base URL; native.maxapi.dev is recommended for Gemini SDKs.

# 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 — Lists available Gemini models. pageSize defaults to 50 and is capped at 1000; pass nextPageToken back as pageToken to continue.
• GET /v1beta/models/{model} — Returns metadata for one model. Use the short ID returned after models/.

Responses use Google's Model and ListModelsResponse field names, including name, baseModelId, version, displayName, token limits, supportedGenerationMethods, and nextPageToken.

MaxAPI structured model catalogue

Use MaxAPI's public JSON catalogue when you need documentation and product metadata instead of an SDK-compatible response.

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

No API key is required. The catalogue includes public_model_id, display_name, kind, route_modes, documentation links, supported options, images, and pricing summaries. It is a public documentation catalogue and is not filtered for a specific API key; use /v1/models or /v1beta/models to discover models available to a key.

Common request knobs

• route_mode: official | official-cheap | mix. Pass in the JSON body, or as X-MaxAPI-Route-Mode on Gemini-native.

  These are recognized route values, not a promise that every model supports every route. Availability depends on the model, enabled routes and your account.

  Routing precedence: a configured API key route_modes list takes priority over the request. Otherwise, an explicit request route is used; if neither is set, the model default applies. Check the API key settings before comparing route prices.

• asset_delivery: default or mirror. Image URLs and white-label CDN
• async: true queues the request and returns a task id; poll the returned poll_url for completion.

Async tasks

On api.maxapi.dev, an image request accepted with async: true returns HTTP 202. An accepted image request on async.maxapi.dev returns HTTP 200 with a task id and poll_url, not a completed image. Poll that URL with the same API key until status is succeeded, failed or canceled. On success, read data[].url; on failure, read error. Do not treat HTTP 200 alone as generation success.

An accepted Gemini-native async request returns HTTP 200 with an Operation and done: false. Poll GET /v1beta/operations/{task_id} with the same API key until done: true. Then check error; on success, read response.candidates[].content.parts[].fileData.fileUri. Async output uses hosted image URLs, not inlineData.

Async tasks already return image URLs after completion; no extra response_format parameter is needed. Set the CDN delivery option when submitting the task: it is stored with the task and applied to its output URLs. Adding it only when polling does not change that task’s delivery choice.

Image URLs and white-label CDN

For hosted image URLs, default uses https://cdn.maxapi.dev and mirror uses the white-label domain https://cdn.dshsdh.space. On /v1/images/generations and /v1/images/edits, submit "asset_delivery": "mirror" in JSON, or asset_delivery=mirror as a multipart form field.

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"
  }'

On Gemini-native requests, choose the white-label CDN with the request header X-MaxAPI-Asset-Delivery: mirror, not an asset_delivery field in the JSON body. This selects the domain for hosted fileData URLs; it does not turn inlineData into a URL. For synchronous URL output, also set 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/...

White-label delivery changes the asset URL domain, not the API base URL. It does not make API calls unauthenticated, hide the caller’s identity from MaxAPI, or disable request and billing records. Treat generated image URLs as shareable links, not private storage.

Account balance

GET /v1/account/balance returns the key owner's wallet balance. available is spendable now, frozen_micro_credits is held by in-flight async tasks, and 1 credit = 1 USD. Same bearer key, works on every base URL.

Authenticate with the API key whose account balance you want to check.

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: credits available to spend now.
• frozen_micro_credits: credits reserved by in-flight asynchronous tasks.
• total_micro_credits: available and reserved credits combined.
• available_usd: the available balance rendered in USD.
• status: the wallet status.

Multiple API keys under the same account share one wallet, so they return the same balance. This endpoint reports the real-time account balance. Use the per-key billing endpoint below for historical spend.

OpenAI-style balance tools can read it unchanged from GET /dashboard/billing/subscription (balance in hard_limit_usd) and GET /dashboard/billing/usage. The usage compatibility endpoint does not return historical per-key usage.

new-api balance compatibility

GET /api/usage/token implements the API-key quota response used by QuantumNous/new-api. Authenticate with the API key you want to inspect; a key can inspect only itself.

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
#   }
# }

The quota fields use new-api's default integer units: 500,000 quota equals 1 USD. total_used is this key's settled usage for the current UTC month; total_available is the lesser of the shared spendable wallet and this key's remaining monthly limit.

sub2api balance compatibility

GET /v1/usage implements the API-key balance response used by Wei-Shaw/sub2api. It accepts Authorization: Bearer, x-api-key, or x-goog-api-key; API keys in query strings are not accepted.

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"
#   }
# }

Values are in USD. balance is the shared wallet amount. remaining is the amount this key can actually spend after applying both the wallet and its monthly limit. Keys without a monthly limit return mode unrestricted and omit quota.

Per-API-key billing usage

GET /v1/account/billing/usage returns the shared current balance and historical usage for only the bearer API key. A caller cannot select or inspect another key.

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"

By default, the endpoint returns the current UTC month through now. Use RFC3339 from (inclusive) and to (exclusive), limit (1–500), and the returned cursor for older rows.

Summary and model totals cover the entire time range, while data contains one page of request details. Charges are final settled amounts after the key's pricing multiplier.

The balance object is shared by all keys on the account. monthly_quota identifies this key's current UTC-month limit, usage, and remaining quota; unlimited keys return null limit and remaining values.

Per-model API reference

• 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

Machine-readable indexes

• /llms.txt — high-level platform summary.
• /docs/llms.txt — documentation-focused plaintext.
• /models.json — structured model catalogue.
• /pricing.json — structured per-route pricing.