Chat Completions

The main surface. OpenAI-compatible, so the request and response shapes are what SDKs already expect.

Parameters

Auto router (iranrouter/auto)

Three fixed IDs: iranrouter/auto:cheap, iranrouter/auto:balanced and iranrouter/auto:best (iranrouter/auto without a tier is balanced). Each is a chain of up to three models we maintain and revise over time; your request runs like a models chain: the first model, then the next if it could not answer or your key, plan or a guardrail does not allow it. You always pay the price of the model that answered, named in X-IranRouter-Model-Used, in the response's model field and on the usage page; a tier has no price of its own. The tiers are listed by GET /v1/models, without a price. A tier that currently has no models is 404 model_not_found. If you put your own model in front of a tier (your model, the tier in models), the cap of three leaves room for two of the tier's, and a refusal of your own model is still a 403. In a tool loop, the model that answered the first turn takes every later turn. To choose the models yourself, use models or a preset.

Idempotency-Key

On a non-streaming request, an Idempotency-Key header (up to 200 characters) answers a retry from memory and never bills twice. A replayed response carries x-idempotent-replay: true. While the original is still running you get 409 idempotency_in_flight; if the original response was too large to store, 409 idempotency_completed_unreplayable. Ignored on streams.

Conversation and app (session_id, X-Title)

A session_id in the body, or an x-session-id header (up to 256 characters), ties the turns of one conversation together: they stay on one route so the prompt cache stays warm and the repeated prefix costs less, and the usage log finds them by that id. Without it, prompt_cache_key, then user (or metadata.user_id), then a fingerprint of the conversation's opening is used; the X-IranRouter-Session response header says which. session_id and prompt_cache_key are stored as sent so you can find your own session — do not put personal data in them; user and the fingerprint are stored only as a keyed hash. The value of none of these fields goes upstream; the upstream sees only an opaque key that is never shared between customers.

The X-Title and HTTP-Referer headers name your app, so usage can be read per app. Only the origin of the referer is kept.

Route preference (provider)

A provider object in the body orders or restricts the upstream routes. It depends on the plan: without it the field is silently ignored and the response carries an explanatory X-IranRouter-Provider-Prefs header; with it, an invalid value is a 400 with code invalid_provider_prefs. The field is never forwarded upstream.

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767000000,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 108,
    "total_tokens": 132,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "cost_rial": 1840
  }
}

The usage.cost_rial field is this request's final charge in Rial. The class counts come both under OpenAI's names — prompt_tokens_details.cached_tokens (plus cache_write_tokens, audio_tokens, image_tokens where present) and completion_tokens_details.reasoning_tokens (plus audio_tokens, image_tokens) — and under our flat names: cached_input_tokens, cache_write_tokens, reasoning_tokens and so on. On a stream the same object arrives on the last chunk.

The non-streaming path returns tool_calls, logprobs, refusal and n>1 in full.

Full example

curl https://iranrouter.com/v1/chat/completions \
  -H "Authorization: Bearer ir-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You answer in Persian."},
      {"role": "user", "content": "پایتخت ایران کجاست؟"}
    ],
    "max_tokens": 200,
    "temperature": 0.4
  }'

Plugins and transforms

Two optional fields, under the names OpenRouter's clients already send. Both are run by us; an unknown name is a 400, so a plugin that does nothing is never mistaken for one that is broken.

For streaming → · For tools →