REFERENCE

API reference

Every endpoint in full: request parameters, response schemas and examples. Generated from the same spec as the API itself.

Base URL is https://api.altrouter.ai/v1. Machine-readable spec: openapi.json — import into Postman, Insomnia or a client generator.

Create chat completion

POST/v1/chat/completions

Text and multimodal completions, with optional streaming and tool calling.

Body parameters

modelstringrequired

A model id from the catalog, e.g. "gpt-5.4". See GET /v1/models.

messagesarrayrequired

The conversation: an array of messages with roles system / user / assistant / tool. Supports multimodal content (text + image_url).

streambooleandefault false

If true, the reply streams as OpenAI-compatible server-sent events (SSE). The stream ends with data: [DONE].

max_tokensinteger

Maximum tokens to generate. The alias max_completion_tokens is also accepted. Defaults to a server-side cap.

Claude validates the value against its output cap (8192) and returns a 400 if you exceed it; other models clamp silently.

temperaturenumber0–2default 1

Sampling randomness. Higher is more creative, lower is more deterministic.

Gemini models. GPT-5 and Claude do not take sampling parameters.

top_pnumber0–1default 1

Nucleus sampling — the probability mass to sample tokens from.

Gemini models. GPT-5 and Claude do not take sampling parameters.

stoparray

A string or array of strings at which generation stops.

toolsarray

Function-calling tool definitions in OpenAI format.

Models with the "tools" capability.

tool_choiceobject

Controls tool use: auto / required / none / a specific function.

reasoning_effortstringlow | medium | high | xhigh

Thinking budget for reasoning models. Reasoning content is returned in message.reasoning_content.

Reasoning models, but each family takes a different range: gpt-5.4/5.5 accept low…xhigh, gpt-5.2 low or high, Gemini low/medium/high, and Claude is binary (any value enables thinking). The model page lists the live values.

response_formatobject

Structured output: { "type": "json_object" } or { "type": "json_schema", "json_schema": … }. See the Structured outputs guide.

Gemini and GPT models. Not supported by Claude models.

web_searchbooleandefault false

Server-side web search: the model answers with live data from the web.

Every GPT-5.x model and most Gemini models — wherever the request routes through kie. Not supported by Claude. The model page lists it where available.

seedinteger

Seed for reproducible sampling where the model supports it.

Gemini models only. GPT-5.x and Claude do not take sampling parameters.

frequency_penaltynumber−2–2

Penalizes tokens by their existing frequency.

Gemini models only. GPT-5.x and Claude do not take sampling parameters.

presence_penaltynumber−2–2

Penalizes tokens that have already appeared.

Gemini models only. GPT-5.x and Claude do not take sampling parameters.

Response

idstring

Completion id.

objectstring

Always "chat.completion".

createdinteger

Unix creation time (seconds).

modelstring

Model that served the request.

choicesarray

Completions. Each: index, message { role, content, reasoning_content, tool_calls }, finish_reason.

usageobject

Tokens: prompt_tokens, completion_tokens, total_tokens.

Example

cURLJSON

curl https://api.altrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"Hi"}]}'

Errors

400Invalid request.

401Missing or invalid API key.

402Insufficient credits, or the key’s spending cap is exhausted.

403The surface is outside the key’s scopes.

404Model not found.

429Rate limit exceeded.

500Internal gateway error.

502Model-side error.

503The model is temporarily unavailable.

504Request exceeded the allowed time.

Create image

POST/v1/images/generations

Generate or edit an image. The result is re-hosted on our CDN and returned as a URL.

Body parameters

modelstringrequired

An image model id from the catalog, e.g. "nano-banana-pro".

promptstringrequired

A text description of the desired image.

imagearray

Reference images (URL or base64) for editing. The router picks the model’s edit variant automatically.

Edit-capable models.

resolutionstring1K | 2K | 4K

Resolution tier — selects the model variant and price (quality:"hd" ⇒ 4K).

Where the model offers multiple resolutions.

response_formatstringurl | b64_jsondefault url

Result shape. Defaults to url: the image is re-hosted on our CDN and the link is permanent.

Response

createdinteger

Unix creation time (seconds).

dataarray

Images. Each: url (our CDN), b64_json, revised_prompt.

Example

cURLJSON

curl https://api.altrouter.ai/v1/images/generations \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-pro","prompt":"a red fox"}'

Errors

400Invalid request.

401Missing or invalid API key.

402Insufficient credits, or the key’s spending cap is exhausted.

403The surface is outside the key’s scopes.

404Model not found.

429Rate limit exceeded.

500Internal gateway error.

502Model-side error.

503The model is temporarily unavailable.

504Request exceeded the allowed time.

Create video

POST/v1/videos

Asynchronous: the call returns immediately in queued and you poll GET /v1/videos/{id} for the result. Credit is reserved on create and charged only for a completed render.

Body parameters

modelstringrequired

A video model id from the catalog, e.g. "veo-3.1-fast".

promptstringrequired

A text description of the scene.

secondsinteger

Clip length in seconds. The allowed values are the model’s own (see its page); out-of-range values are clamped. `duration` is accepted as an alias.

imagearray

A reference frame (URL or base64) — its presence routes the request to the model’s image-to-video variant. `input_reference` is accepted for a single frame.

Models with image-to-video (Hailuo 2.3 requires one).

Response

idstring

The render id (vid_…) — this is what you poll.

objectstring

Always "video".

statusstring

queued · in_progress · completed · failed.

created_atinteger

Unix creation time (seconds).

completed_atinteger

Unix completion time (seconds), on terminal statuses.

secondsinteger

The clip length the price was computed on.

urlstring

The finished mp4 on our CDN — appears at status: completed.

errorobject

Why it failed at status: failed: { code, message }.

Example

cURLJSON

curl https://api.altrouter.ai/v1/videos \
  -H "Authorization: Bearer ar-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1-fast","prompt":"a drone shot over a coastline","seconds":8}'

curl https://api.altrouter.ai/v1/videos/vid_... -H "Authorization: Bearer ar-..."

Poll with GET /v1/videos/{id}, list recent renders with GET /v1/videos, and follow GET /v1/videos/{id}/content for a 302 to the file.

Errors

400Invalid request.

401Missing or invalid API key.

402Insufficient credits, or the key’s spending cap is exhausted.

403The surface is outside the key’s scopes.

404Model not found.

429Rate limit exceeded.

500Internal gateway error.

502Model-side error.

503The model is temporarily unavailable.

504Request exceeded the allowed time.

List models

GET/v1/models

The catalog of callable models with per-model pricing (USD) and available params. Takes no query parameters.

Response

List object: { object: "list", data: Model[] }. Model fields:

idstring

Model id.

objectstring

Always "model".

createdinteger

Unix timestamp (seconds).

owned_bystring

Always "altrouter".

surfacestring

"chat", "image" or "video".

context_lengthinteger

Context window in tokens (chat models).

pricingobject

Our price in USD. Chat: prompt_per_1m_usd, completion_per_1m_usd. Image: per_image_usd. Video: per_second_usd or per_video_usd. approximate flag = pre-flight estimate.

paramsarray

Tunable params: key, type, min/max/step or options.

Example

cURLJSON

curl https://api.altrouter.ai/v1/models -H "Authorization: Bearer ar-..."

Errors

401Missing or invalid API key.

Get credit balance

GET/v1/credits

The remaining balance for the account that owns the key. Takes no query parameters.

Response

objectstring

Always "credits".

available_usdnumber

Spendable balance (balance minus holds), USD.

balance_usdnumber

Total settled balance, USD.

held_usdnumber

Reserved by in-flight requests, USD.

Example

cURLJSON

curl https://api.altrouter.ai/v1/credits -H "Authorization: Bearer ar-..."

NextParameters →