MaxAPI documentation
MaxAPI exposes hosted image, video, and language models through documented endpoints. Authentication is a bearer token in the Authorization header. 1 credit = 1 USD; failed generation tasks are not charged. Each public model exposes one or more route_mode tiers that change pricing per request.
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 — generation requests default to async (returns a task id to poll), so you don't need to pass async:true.
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} for asynchronous media tasks.
- OpenAI text/embeddings: /v1/chat/completions, /v1/responses, /v1/embeddings (relayed; no public model seeds by default).
- Account and balance: GET /v1/account/balance, GET /v1/account/billing/usage, new-api-compatible GET /api/usage/token, and sub2api-compatible GET /v1/usage.
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, or mix. Pass in the JSON body or as X-MaxAPI-Route-Mode on Gemini-native.asset_delivery: default or mirror. Mirror rewrites returned URLs to the alias CDN domain.async: true queues the request and returns a task id; poll the returned poll_url for completion.
Account balance
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"
available is spendable now, frozen_micro_credits is reserved by in-flight asynchronous tasks, and total_micro_credits combines available and reserved credits. available_usd renders the available balance in USD.
Multiple API keys under the same account share one wallet, so they return the same balance. This endpoint reports the real-time account balance. The OpenAI-compatible /dashboard/billing/usage endpoint is for balance-tool compatibility and 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"
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"
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; query each key with its own Bearer token.
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. balance is the shared wallet snapshot; monthly_quota is this key's current UTC-month limit, usage, and remaining quota. Summary and model totals cover the requested time range; detail charges are final settled amounts after the key's pricing multiplier.