Docs

# Developer docs

aictrlx speaks the OpenAI Chat Completions API: point any OpenAI SDK or tool at the base URL below, use a routing mode or a model id as `model`, and read why each request went where it did.

**Base URL**: `https://aictrlx.ru/v1`

**Auth**: `Authorization: Bearer aictrlx_live_...`

## 5-minute quickstart

1.  ### Create an API key
    
    [Create an account](https://aictrlx.ru/register) (or [log in](https://aictrlx.ru/login)), then create a key on the API Keys page. Keys look like `aictrlx_live_...` and are shown only once.
    
2.  ### Put the key in an environment variable
    
    Every example below reads the key from `AICTRLX_API_KEY`, so it never ends up in your code.
    
    Shell
    
    ```
    export AICTRLX_API_KEY="aictrlx_live_..."
    ```
    
3.  ### Send your first request
    
    curl
    
    ```
    curl https://aictrlx.ru/v1/chat/completions \
      -H "Authorization: Bearer $AICTRLX_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "auto",
        "messages": [{"role": "user", "content": "Say hello in one short sentence."}]
      }'
    ```
    
    The response is a standard OpenAI `chat.completion` plus an `aictrlx` object that explains the routing decision (see Routing metadata).
    
4.  ### See what happened
    
    Open the request log in the app to see the request with its routing explanation, tokens, cost and latency. To try prompts without code, use the Playground.
    

## Python

Use the official `openai` package; only `base_url` and the key change.

Install

```
pip install openai
```

Python

```
import os

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

response = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain MVCC in PostgreSQL in two sentences."},
    ],
)
print(response.choices[0].message.content)
print("served by:", response.model)  # the model that actually answered
print(response.usage)
```

## JavaScript / TypeScript

Use the official `openai` npm package. The examples are ES modules with top-level `await`: save them as `.mts` and run `npx tsx example.mts` (or drop the type annotations for plain `.mjs`).

Install

```
npm install openai
```

TypeScript

```
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://aictrlx.ru/v1",
  apiKey: process.env.AICTRLX_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "auto",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain MVCC in PostgreSQL in two sentences." },
  ],
});
console.log(completion.choices[0].message.content);
console.log("served by:", completion.model); // the model that actually answered
console.log(completion.usage);
```

## curl

Chat completion

```
curl https://aictrlx.ru/v1/chat/completions \
  -H "Authorization: Bearer $AICTRLX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Say hello in one short sentence."}]
  }'
```

List the models your key can use

```
curl https://aictrlx.ru/v1/models \
  -H "Authorization: Bearer $AICTRLX_API_KEY"
```

## Streaming

Set `stream: true` to receive Server-Sent Events. With `stream_options.include_usage` the last chunk carries token usage, and the final chunks also carry the `aictrlx` routing metadata.

Streaming · Python

```
import os

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a Python function that reverses a linked list."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:  # last chunk: token usage plus the routing metadata
        print("\n", chunk.usage)
        print(chunk.model_extra.get("aictrlx"))
```

## Routing modes & models

Pass a routing mode as `model` to let the router pick the best available model per request, or pass an exact model id to pin one.

| model | Behaviour |
| --- | --- |
| auto | Classifies the request, then uses a task-specific policy (coding → coding, reasoning → smart, simple Q&A → fast, otherwise balanced). |
| fast | Latency first, then availability and cost, above a minimum quality floor. |
| smart | Quality and reasoning first, then reliability, then latency and cost. |
| coding | Coding ability, context size and tool support, then quality, then latency and cost. |

[Log in](https://aictrlx.ru/login) to see the models available on this deployment, or call `GET https://aictrlx.ru/v1/models` with your key.

## Routing metadata & headers

Every response carries an `aictrlx` object (on streams: in the final chunk and the usage chunk) and `X-Aictrlx-*` headers that explain the routing decision.

Read routing metadata · Python

```
import os

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

raw = client.chat.completions.with_raw_response.create(
    model="auto",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print(raw.headers.get("x-aictrlx-model"), raw.headers.get("x-aictrlx-provider"))
print("requests left this minute:", raw.headers.get("x-ratelimit-remaining"))

response = raw.parse()
aictrlx = response.model_extra["aictrlx"]
print(aictrlx["routing_policy"], aictrlx["task_type"], aictrlx["actual_model"])
print("fallbacks:", aictrlx["fallback_count"], "cost, RUB:", aictrlx["estimated_cost_rub"])
```

### The `aictrlx` object

| Field | Meaning |
| --- | --- |
| request_id | Inference id: use it for feedback and to find the request in the request log. |
| routing_mode | auto, fast, smart, coding, or explicit (an exact model id was requested). |
| routing_policy | Policy actually applied: fast, smart, coding or balanced. |
| task_type, task_confidence | What the classifier recognised (coding, reasoning, simple_qa, …) and how sure it was. |
| selected_model | The router's first choice. |
| actual_model, provider | The model and provider that produced the answer (differs from selected_model after a fallback). |
| candidates | Ordered candidate list the router would try. |
| fallback_count, attempts | How many candidates failed before the answer, and the total upstream attempts. |
| ttft_ms, latency_ms | Time to first token and total latency, in milliseconds. |
| input_tokens, output_tokens | Token usage. |
| usage_source | provider (reported by the provider) or estimated (the provider reported none). |
| estimated_cost_rub | Cost of the request in roubles at the current prices, as a decimal string. |
| finish_reason | stop, length, tool_calls or content_filter. |

### Response headers

| Header | Meaning |
| --- | --- |
| X-Aictrlx-Inference-Id | Same value as aictrlx.request_id. |
| X-Aictrlx-Model, X-Aictrlx-Provider | Model and provider that served the request. On a stream they are sent only when the first token arrives quickly; a slow (thinking) model starts the stream before routing finishes, so read aictrlx from the final chunk instead. |
| X-Aictrlx-Routing-Mode, X-Aictrlx-Task-Type | Routing mode and classified task (non-streaming responses). |
| X-Aictrlx-Cache | Only when the project's response cache is on: hit, miss or refresh. Send X-Aictrlx-Cache: bypass to skip the cache, or refresh to fetch a new answer and replace the cached one. |
| X-RateLimit-Limit, X-RateLimit-Remaining | This key's requests per minute and what is left in the current window. |
| Retry-After | On 429: seconds to wait before retrying. The error body carries the same number as error.retry_after (inside a stream only the body has it). |
| X-Request-ID | Correlation id for logs and support; also echoed as error.request_id. You may send your own. |

### Rate a response

Feedback is linked to the request and shown with it in the request log.

curl

```
curl -X POST https://aictrlx.ru/api/v1/feedback \
  -H "Authorization: Bearer $AICTRLX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "<aictrlx.request_id or the chatcmpl-... id>", "rating": "positive", "comment": "great answer"}'
```

## Tool calling

Tools use the OpenAI format, streaming and non-streaming. Requests with tools are routed only to models that support tools; `tool_choice: "required"` or a named function also needs forced tool choice support. Keep sending the same `model` on every turn: the platform keeps a tool loop on the model that started it.

Tool calling (two turns) · Python

```
import json
import os
from datetime import datetime
from zoneinfo import ZoneInfo

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Current local time in an IANA time zone",
            "parameters": {
                "type": "object",
                "properties": {"timezone": {"type": "string", "description": "e.g. Asia/Tokyo"}},
                "required": ["timezone"],
            },
        },
    }
]

def get_current_time(timezone: str) -> str:
    return datetime.now(ZoneInfo(timezone)).isoformat(timespec="seconds")

messages = [{"role": "user", "content": "What time is it in Tokyo right now?"}]

# Turn 1: the model asks for a tool call.
first = client.chat.completions.create(model="auto", messages=messages, tools=tools)
message = first.choices[0].message
if not message.tool_calls:
    print(message.content)  # the model answered without calling the tool
else:
    messages.append(message.model_dump(exclude_none=True))
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        messages.append(
            {"role": "tool", "tool_call_id": call.id, "content": get_current_time(args["timezone"])}
        )

    # Turn 2: send the tool results back; the loop stays on the model that started it.
    final = client.chat.completions.create(model="auto", messages=messages, tools=tools)
    print(final.choices[0].message.content)
```

## JSON mode

`response_format: {"type": "json_object"}` routes only to models with JSON support and asks them for a single JSON object. Mention JSON in your prompt. `json_schema` is rejected with `400`: validate the parsed object on your side.

JSON mode · Python

```
import json
import os

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

response = client.chat.completions.create(
    model="auto",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with a JSON object only."},
        {"role": "user", "content": "Extract the city and the date (ISO 8601) as JSON with the keys city and date: Meet me in Lisbon on 12 May 2027."},
    ],
)
data = json.loads(response.choices[0].message.content)
print(data["city"], data["date"])
```

## Images, PDF and audio

A user message may carry content parts besides text: `image_url` (an https URL, or a `data:` URI with base64 of PNG, JPEG, GIF or WebP), `file` (a PDF as a `data:application/pdf;base64,…` URI in `file_data`, with a `filename`) and `input_audio` (base64 of wav or mp3). `auto` and the other modes send such a request only to models that take its attachments; a model named explicitly that does not answers `400` `image_input_not_supported` (`file_input_not_supported`, `audio_input_not_supported`). `GET /v1/models` shows it in `capabilities.vision`, `files` and `audio`. A request may be up to 25 MB with up to 100 attachments. The Anthropic-compatible API takes `image` and `document` blocks the same way, images in tool results too. In the Playground files are attached with «Attach», pasted or dropped on the chat; pictures larger than 2048 px are scaled down in the browser first.

An image and a PDF in one request · Python

```
import base64
import os

from openai import OpenAI

client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"])

with open("chart.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
with open("report.pdf", "rb") as f:
    report = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="auto",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Does the chart match the report?"},
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
                {"type": "file", "file": {"filename": "report.pdf", "file_data": f"data:application/pdf;base64,{report}"}},
            ],
        }
    ],
)
print(response.choices[0].message.content)
```

## For agents: sessions & reasoning

What a coding agent needs on top of the OpenAI format: one model per session (the provider keeps its prompt cache), the reasoning of thinking models, what each model can do, and errors that say what to do next.

| Name | Meaning |
| --- | --- |
| X-Aictrlx-Session | Request header: any id of your session (1–128 characters: letters, digits, . _ : -). With a routing mode (auto, fast, smart, coding) the requests of one session go to the model that answered the last one, as long as it can serve them (context, tools); otherwise another model takes over and the session continues on it. Kept for 6 hours after the last request. |
| reasoning_content | In responses: the reasoning of a thinking model (e.g. DeepSeek … thinking): message.reasoning_content, or delta.reasoning_content chunks before the answer on a stream. Other models do not send it. |
| messages[].reasoning_content | In requests: send it back on the assistant messages it came with. With tools, a thinking model needs the reasoning of every earlier assistant message; the platform also remembers it for 24 hours, and routes a conversation whose reasoning it does not know to a model without thinking (an explicit thinking model then returns 400 reasoning_history_missing). Other models never receive it. |
| reasoning_effort | How hard a thinking model reasons: minimal, low, medium, high, xhigh or max; none turns thinking off for the request. Models without thinking ignore it. |
| GET /v1/models | Besides id and owned_by: context_window and max_output_tokens (tokens), capabilities (streaming, tools, forced_tool_choice, json_mode, vision, files, audio, reasoning, reasoning_effort, temperature, prompt_caching) and, for models, pricing per 1M tokens (USD, and roubles when billing is on). For a routing mode: the largest window and answer among its models and what any of them can do. Attachments: vision (images), files (PDF) and audio. |
| 400 context_length_exceeded | The conversation does not fit any available model (or the provider says so): error.message gives the estimate and the largest window. Shorten the history or max_tokens; retrying as is will not help. |
| error.retry_after, error.status | Seconds to wait (rate limits) in every error that has Retry-After. An error inside a stream (the response already started with 200) also carries the HTTP status it stands for. |
| Limits | Up to 500 messages (the operator's MAX_MESSAGES_PER_REQUEST) and 128 tools per request, as in the OpenAI API. |

## Errors & rate limits

Errors use the OpenAI envelope `{"error": {"message", "type", "code", "param", "request_id"}}`, so the SDKs raise their usual exception classes and `code` tells you what happened. Errors that say how long to wait also carry `retry_after` (seconds).

| HTTP | code | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | validation_errorunsupported_parameterunsupported_content_typeinvalid_attachmenttoo_many_attachmentsimage_input_not_supportedfile_input_not_supportedaudio_input_not_supportedcontext_length_exceededreasoning_history_missinginvalid_session_idcontent_filteredupstream_invalid_request | Invalid or unsupported request: image inputs, json_schema, legacy functions, n > 1, or the provider rejected it. | Fix the request. Retrying will not help. |
| 401 | missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired | No key, an unknown key, or a revoked or expired key. | Send Authorization: Bearer aictrlx_live_…; create a new key if it was revoked or has expired. |
| 403 | project_inactiveaccount_disabledmodel_not_allowed | The key's project is deactivated, the account is disabled, or the key's allowed models do not include the requested model or routing mode. | Re-activate the project on the Projects page; use a model the key allows (GET /v1/models lists them). |
| 404 | model_not_found | The model is neither a routing mode nor a registry model id. | Use auto, fast, smart, coding or an id from GET /v1/models. |
| 429 | rate_limit_exceededupstream_rate_limited | This key's per-minute limit, or every candidate provider rate-limited the request. | Wait error.retry_after (= Retry-After) seconds, then retry. The OpenAI SDKs do this automatically. |
| 429 | monthly_quota_exceededdaily_quota_exceededproject_budget_exceededkey_budget_exceeded | Error type insufficient_quota: the platform credit, the project's monthly budget or this key's monthly budget is used up. | Retrying will not help until the period resets; the owner can raise or remove the budget. |
| 502 | upstream_error | Every routing candidate failed (after retries and fallback). | Retry with backoff. |
| 503 | no_routing_candidatesmodel_unavailablerate_limiter_unavailable | No available model can serve the request (e.g. it needs tools or JSON mode, or no provider is configured), the requested model is unavailable, or rate limiting is temporarily down. | Check the Models page; try another mode or model. |
| 504 | upstream_timeout | The provider timed out on every candidate. | Retry, use a smaller max_tokens or the fast mode. |

**Rate limits.** Each API key has a per-minute limit (a sliding 60-second window); every response reports it in `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Over the limit you get `429` with `Retry-After` in seconds. The OpenAI SDKs retry 429 and 5xx responses twice by default and honour `Retry-After`.

Handle errors · Python

```
import os

import openai
from openai import OpenAI

# The SDK already retries 429 and 5xx responses (honouring Retry-After); max_retries=0 shows the raw errors.
client = OpenAI(base_url="https://aictrlx.ru/v1", api_key=os.environ["AICTRLX_API_KEY"], max_retries=0)

try:
    response = client.chat.completions.create(
        model="auto",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)
except openai.AuthenticationError as e:  # 401: missing, invalid or revoked key
    print("auth:", e.code)
except openai.NotFoundError as e:  # 404 model_not_found
    print("unknown model:", e.code)
except openai.RateLimitError as e:  # 429: wait Retry-After seconds
    print("rate limited:", e.code, "retry after", e.response.headers.get("retry-after"), "s")
except openai.APIStatusError as e:  # 400, 403, 502, 503, 504...
    print("HTTP", e.status_code, e.code)
except openai.APIError as e:  # e.g. an error event after a stream started
    print("API error:", e.message)
```

## Anthropic Messages API

The same keys, routing modes and models also work through `POST /v1/messages`, so the official `anthropic` SDKs and Claude Code can use this deployment. Send the key as `x-api-key` or `Authorization: Bearer`. The SDK base URL is `https://aictrlx.ru` (without `/v1`): the SDKs add `/v1/messages` themselves.

Anthropic Messages API · Python

```
import os

import anthropic

client = anthropic.Anthropic(base_url="https://aictrlx.ru", api_key=os.environ["AICTRLX_API_KEY"])

message = client.messages.create(
    model="auto",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(message.model)  # the model that actually answered
print(message.content[0].text)
print(message.model_extra["aictrlx"])  # routing metadata, as on /v1/chat/completions
```

### Claude Code

[Claude Code with aictrlx →](https://aictrlx.ru/docs/claude-code)

Point Claude Code at this deployment and map its model tiers to routing modes (any model id from above works too):

Shell

```
export ANTHROPIC_BASE_URL="https://aictrlx.ru"
export ANTHROPIC_AUTH_TOKEN="$AICTRLX_API_KEY"
# Claude Code's model tiers -> routing modes of this platform
export ANTHROPIC_DEFAULT_OPUS_MODEL=smart
export ANTHROPIC_DEFAULT_SONNET_MODEL=coding
export ANTHROPIC_DEFAULT_HAIKU_MODEL=fast
```

Not supported on this endpoint: image and document input, server tools (web search, code execution), `mcp_servers` and extended thinking output. Unknown Claude model names are rejected unless the operator maps them with `MESSAGES_API_MODEL_ALIASES`.

## Integrations

Any tool that lets you set an OpenAI-compatible base URL works. Use the base URL above and your key.

### Cursor

[Cursor with aictrlx →](https://aictrlx.ru/docs/cursor)

1.  Open **Cursor Settings → Models**.
2.  Under **API Keys**, paste your key into **OpenAI API Key** and enable it.
3.  Enable **Override OpenAI Base URL** and enter `https://aictrlx.ru/v1`.
4.  Add custom models named `auto`, `smart`, `coding` (or any model id from above) and pick one in chat.

Cursor sends these requests from its own servers, so the base URL must be reachable from the internet. Tab completion keeps using Cursor's built-in models.

### Continue

[Continue with aictrlx →](https://aictrlx.ru/docs/continue)

Add the models to `~/.continue/config.yaml` (provider `openai` with `apiBase`), replacing the key placeholder:

config.yaml

```
name: aictrlx
version: 0.0.1
schema: v1

models:
  - name: aictrlx auto
    provider: openai
    model: auto
    apiBase: https://aictrlx.ru/v1
    apiKey: aictrlx_live_...
  - name: aictrlx coding
    provider: openai
    model: coding
    apiBase: https://aictrlx.ru/v1
    apiKey: aictrlx_live_...
```

### LangChain

[LangChain with aictrlx →](https://aictrlx.ru/docs/langchain)

Install

```
pip install langchain-openai
```

Python

```
import os

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="auto",
    base_url="https://aictrlx.ru/v1",
    api_key=os.environ["AICTRLX_API_KEY"],
)
reply = llm.invoke("Explain vector databases in two sentences.")
print(reply.content)
print(reply.response_metadata.get("model_name"))  # the model that actually answered
```

### Vercel AI SDK

[Vercel AI SDK with aictrlx →](https://aictrlx.ru/docs/vercel-ai-sdk)

Use `createOpenAI` with `baseURL` and the `.chat()` model factory: this API implements Chat Completions, not the Responses API.

Install

```
npm install ai @ai-sdk/openai
```

TypeScript

```
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const aictrlx = createOpenAI({
  baseURL: "https://aictrlx.ru/v1",
  apiKey: process.env.AICTRLX_API_KEY,
});

// aictrlx.chat(...) uses the Chat Completions API; plain aictrlx(...) would call the Responses API.
const { text, response } = await generateText({
  model: aictrlx.chat("auto"),
  prompt: "Explain vector databases in two sentences.",
});
console.log(text);
console.log(response.modelId); // the model that actually answered
```

### LiteLLM

[LiteLLM with aictrlx →](https://aictrlx.ru/docs/litellm)

Prefix the model with `openai/` (generic OpenAI-compatible endpoint) and set `api_base`.

Install

```
pip install litellm
```

Python SDK

```
import os

import litellm

response = litellm.completion(
    model="openai/auto",  # "openai/" = any OpenAI-compatible endpoint
    api_base="https://aictrlx.ru/v1",
    api_key=os.environ["AICTRLX_API_KEY"],
    messages=[{"role": "user", "content": "Explain vector databases in two sentences."}],
)
print(response.choices[0].message.content)
```

LiteLLM proxy config.yaml

```
model_list:
  - model_name: aictrlx-auto
    litellm_params:
      model: openai/auto
      api_base: https://aictrlx.ru/v1
      api_key: os.environ/AICTRLX_API_KEY
  - model_name: aictrlx-coding
    litellm_params:
      model: openai/coding
      api_base: https://aictrlx.ru/v1
      api_key: os.environ/AICTRLX_API_KEY
```

## Need a key?

Sign up: the key is in the dashboard a minute later.

[Create a free account →](https://aictrlx.ru/register)

## What's new

New models, routing modes and API changes.

[Changelog →](https://aictrlx.ru/docs/changelog)
