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/jsonA 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
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/models | Available model inventory |
| GET | /v1/usage | Scoped usage aggregates |
| POST | /v1/chat/completions | Supported text chat requests |
| POST | /v1/responses | Supported text Responses requests |
| POST | /v1/messages | Supported text messages requests |
| POST | /v1/embeddings | Text embeddings |
| POST | /v1/messages/count_tokens | Input count or estimate, without a credit charge |
| POST | /v1/images/generations, /v1/images/edits | Image generation and editing, charged per image or image token |
| POST | /v1/audio/speech | Text to speech, charged per character or second |
| POST | /v1/audio/transcriptions, /v1/audio/translations | Speech to text, charged per second of audio |
| POST, GET, DELETE | /v1/videos, /v1/videos/{id}, /v1/videos/{id}/content, /v1/videos/{id}/remix | OpenAI-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
| Status | Meaning | Next step |
|---|---|---|
| 401 | Invalid account API key | Use an active key from your account. |
| 402 | Insufficient credit for reservation | Add credit or reduce your maximum output. |
| 403 | Restricted endpoint or access | Check endpoint support and model access. |
| 400 | Invalid request or BYOK setup | Check the model, saved key, and parameters. |
| 503 | Account or billing service unavailable | Retry 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.