API GUIDE

A familiar interface.

ZRouter translates supported requests for configured model providers. Prepaid accounts use a restricted set of synchronously metered endpoints.

Authentication

Create an account API key in your dashboard and include it in every inference request:

Authorization: Bearer YOUR_ZROUTER_KEY
Content-Type: application/json

A browser session token cannot be used as an inference API key. Account API keys cannot authenticate customer dashboard sessions or grant operator access.

Supported account endpoints

MethodEndpointPurpose
GET/v1/modelsAvailable model inventory
GET/v1/usageScoped usage aggregates
POST/v1/chat/completionsSupported text chat requests
POST/v1/responsesSupported text Responses requests
POST/v1/messagesSupported text messages requests
POST/v1/embeddingsText embeddings
POST/v1/messages/count_tokensInput count or estimate, without a credit charge
POST/v1/images/generations, /v1/images/editsImage generation and editing, charged per image or image token
POST/v1/audio/speechText to speech, charged per character or second
POST/v1/audio/transcriptions, /v1/audio/translationsSpeech to text, charged per second of audio
POST, GET, DELETE/v1/videos, /v1/videos/{id}, /v1/videos/{id}/content, /v1/videos/{id}/remixOpenAI-compatible video jobs on Veo or Sora, charged per second of finished video

Client-executed function tools and inline text tool results are supported on chat, Responses, and Messages endpoints. Send complete history with each turn. Capabilities vary by model and provider. Image and audio requests use the same API key and balance; a model needs a published image, audio, or video price to be used. A video holds its requested length when created and is charged its finished length; failed jobs are free. Media inputs to chat, provider-hosted tools, opaque reasoning replay, background operations, response lifecycle routes, passthrough routes, and the inference MCP proxy remain unavailable through prepaid billing. The separate account MCP server is available for account management with its own management token.

Model selection

Use an identifier from your account’s model list. A provider-qualified model has the format PROVIDER_INSTANCE/MODEL_ID. With BYOK, use either a provider-qualified model or one of your virtual models; see Bring your own keys.

Streaming

For supported chat requests, include "stream": true. The gateway meters token usage as part of request completion. If a stream disconnects before final usage arrives, reserved credit can remain held for reconciliation.

Token limits and reservations

This workspace reserves for up to 131072 input tokens. Its maximum output allowance is 8192 tokens. Set a smaller max_tokens to reduce the output portion of a reservation. Provider limits may be smaller.

The gateway settles the actual metered charge after a completed request. Your balance must cover the initial reservation, which can exceed the final debit.

Common billing errors

StatusMeaningNext step
401Invalid account API keyUse an active key from your account.
402Insufficient credit for reservationAdd credit or reduce your maximum output.
403Restricted endpoint or accessCheck endpoint support and model access.
400Invalid request or BYOK setupCheck the model, saved key, and parameters.
503Account or billing service unavailableRetry later; avoid blindly retrying paid work.

Providers can return additional errors. Treat the error message and response status as part of your application’s error handling.