Документация для разработчиков
aictrlx поддерживает OpenAI Chat Completions API: подключите любой OpenAI SDK или инструмент к базовому URL ниже, передайте в model режим маршрутизации или id модели — и смотрите, почему каждый запрос попал туда, куда попал.
https://aictrlx.ru/v1Authorization: Bearer aictrlx_live_...Старт за 5 минут
Создайте API-ключ
Зарегистрируйтесь (или войдите), затем создайте ключ на странице «API-ключи». Ключи выглядят как
aictrlx_live_...и показываются только один раз.Сохраните ключ в переменной окружения
Все примеры ниже читают ключ из
AICTRLX_API_KEY, поэтому он не попадает в код.Shellexport AICTRLX_API_KEY="aictrlx_live_..."Отправьте первый запрос
curlcurl 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."}] }'Ответ — стандартный
chat.completionOpenAI плюс объектaictrlx, который объясняет решение маршрутизации (см. метаданные маршрутизации).Посмотрите, что произошло
Откройте в кабинете «Журнал запросов», чтобы увидеть запрос с объяснением маршрутизации, токенами, стоимостью и задержкой. Чтобы попробовать промпты без кода, воспользуйтесь песочницей Playground.
Python
Используйте официальный пакет openai: меняются только base_url и ключ.
pip install openaiimport 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
Используйте официальный npm-пакет openai. Примеры — это ES-модули с await на верхнем уровне: сохраните пример в файл .mts и запустите npx tsx example.mts (или уберите аннотации типов и сохраните его как обычный .mjs).
npm install openaiimport 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
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."}]
}'curl https://aictrlx.ru/v1/models \
-H "Authorization: Bearer $AICTRLX_API_KEY"Потоковая передача
Передайте stream: true, чтобы получать ответ в виде Server-Sent Events. С stream_options.include_usage последний фрагмент содержит расход токенов, а завершающие фрагменты — ещё и метаданные маршрутизации aictrlx.
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")): keep-alive, которые SSE-клиенты и SDK пропускают. Если после начала потока все кандидаты завершатся ошибкой, поток закончится событием data: {"error": {…}} вместо [DONE]; SDK выбросят его как ошибку API.Режимы маршрутизации и модели
Передайте в model режим маршрутизации, чтобы маршрутизатор выбирал лучшую доступную модель для каждого запроса, или точный id модели, чтобы закрепить её.
| model | Поведение |
|---|---|
auto | Определяет тип запроса и применяет политику для этого типа задач (код → coding, рассуждение → smart, простой вопрос → fast, остальное → balanced). |
fast | Сначала задержка, затем доступность и стоимость — при соблюдении минимального уровня качества. |
smart | Сначала качество и способность к рассуждению, затем надёжность, затем задержка и стоимость. |
coding | Навыки программирования, размер контекста и поддержка инструментов, затем качество, затем задержка и стоимость. |
Войдите, чтобы увидеть модели, доступные в этом экземпляре, или вызовите GET https://aictrlx.ru/v1/models со своим ключом.
Метаданные маршрутизации и заголовки
Каждый ответ содержит объект aictrlx (в потоке — в последнем фрагменте и во фрагменте с расходом токенов) и заголовки X-Aictrlx-*, которые объясняют решение маршрутизации.
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"])Объект aictrlx
| Поле | Значение |
|---|---|
request_id | Идентификатор запроса: по нему можно оценить ответ и найти запрос в журнале запросов. |
routing_mode | auto, fast, smart, coding или explicit (запрошен точный id модели). |
routing_policy | Фактически применённая политика: fast, smart, coding или balanced. |
task_type, task_confidence | Какой тип задачи определил классификатор (coding, reasoning, simple_qa, …) и насколько он в этом уверен. |
selected_model | Модель, которую маршрутизатор выбрал первой. |
actual_model, provider | Модель и провайдер, которые дали ответ (отличаются от selected_model, если сработало переключение на резервную модель). |
candidates | Упорядоченный список кандидатов, которые маршрутизатор пробует по очереди. |
fallback_count, attempts | Сколько кандидатов не справились до получения ответа и общее число обращений к провайдерам. |
ttft_ms, latency_ms | Время до первого токена и общая задержка, в миллисекундах. |
input_tokens, output_tokens | Расход токенов (вход / выход). |
usage_source | provider (данные провайдера) или estimated (провайдер их не сообщил, значение оценено). |
estimated_cost_rub | Стоимость запроса в рублях по действующим ценам, в виде десятичной строки. |
finish_reason | stop, length, tool_calls или content_filter. |
Заголовки ответа
| Заголовок | Значение |
|---|---|
X-Aictrlx-Inference-Id | То же значение, что и aictrlx.request_id. |
X-Aictrlx-Model, X-Aictrlx-Provider | Модель и провайдер, обработавшие запрос. В потоке они отправляются, только если первый токен приходит быстро: у медленной (рассуждающей) модели поток начинается до завершения маршрутизации, поэтому в этом случае берите aictrlx из последнего фрагмента. |
X-Aictrlx-Routing-Mode, X-Aictrlx-Task-Type | Режим маршрутизации и определённый тип задачи (в ответах без потоковой передачи). |
X-Aictrlx-Cache | Только если у проекта включён кэш ответов: hit, miss или refresh. Отправьте X-Aictrlx-Cache: bypass, чтобы не использовать кэш, или refresh, чтобы получить новый ответ и заменить им сохранённый. |
X-RateLimit-Limit, X-RateLimit-Remaining | Лимит запросов в минуту для этого ключа и остаток в текущем окне. |
Retry-After | При 429: сколько секунд подождать перед повтором. Тело ошибки содержит то же число в error.retry_after (внутри потока оно есть только в теле). |
X-Request-ID | Сквозной идентификатор для логов и поддержки; также возвращается в error.request_id. Можно передать свой. |
Оценка ответа
Оценка привязывается к запросу и отображается вместе с ним в журнале запросов.
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"}'Вызов инструментов
Инструменты описываются в формате OpenAI и работают как с потоковой передачей, так и без неё. Запросы с инструментами направляются только моделям с их поддержкой; для tool_choice: "required" или вызова конкретной функции модель должна также поддерживать принудительный выбор инструмента. Передавайте одно и то же значение model на каждом шаге: платформа ведёт цикл вызовов инструментов на той модели, которая его начала.
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
response_format: {"type": "json_object"} направляет запрос только моделям с поддержкой JSON и просит их вернуть один JSON-объект. Упомяните JSON в промпте. json_schema отклоняется с ошибкой 400: проверяйте разобранный объект на своей стороне.
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"])Картинки, PDF и аудио
Сообщение пользователя может содержать не только текст: image_url (ссылка https или data: URI с base64 картинки PNG, JPEG, GIF или WebP), file (PDF в виде data:application/pdf;base64,… в поле file_data и с filename) и input_audio (base64 файла wav или mp3). auto и другие режимы отправляют такой запрос только моделям, которые принимают его вложения; явно указанная модель без такой поддержки отвечает 400 image_input_not_supported (file_input_not_supported, audio_input_not_supported). В GET /v1/models это видно в capabilities.vision, files и audio. Запрос — до 25 МБ и до 100 вложений. API в формате Anthropic принимает блоки image и document так же, картинки в результатах инструментов тоже. В Playground файлы прикрепляются кнопкой «Прикрепить», вставкой или перетаскиванием в чат; картинки больше 2048 px браузер сначала уменьшает.
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)Для агентов: сессии и рассуждение
Что нужно агенту программирования сверх формата OpenAI: одна модель на сессию (у провайдера сохраняется кэш промпта), рассуждение моделей с мышлением, возможности каждой модели и ошибки, по которым понятно, что делать дальше.
| Название | Значение |
|---|---|
X-Aictrlx-Session | Заголовок запроса: любой id вашей сессии (1–128 символов: латиница, цифры, . _ : -). В режиме маршрутизации (auto, fast, smart, coding) запросы одной сессии идут на модель, которая ответила на предыдущий, пока она может их обработать (контекст, инструменты); иначе запрос берёт другая модель, и сессия продолжается на ней. Хранится 6 часов после последнего запроса. |
reasoning_content | В ответе: рассуждение модели с мышлением (например, DeepSeek … thinking): message.reasoning_content, а в потоке — фрагменты delta.reasoning_content перед ответом. Другие модели его не присылают. |
messages[].reasoning_content | В запросе: возвращайте его в тех сообщениях ассистента, с которыми он пришёл. С инструментами модели с мышлением нужно рассуждение каждого прежнего сообщения ассистента; платформа тоже запоминает его на 24 часа, а разговор, рассуждение которого ей неизвестно, отправляет модели без мышления (явно указанная модель с мышлением вернёт 400 reasoning_history_missing). Другим моделям оно не передаётся. |
reasoning_effort | Насколько глубоко рассуждает модель с мышлением: minimal, low, medium, high, xhigh или max; none выключает мышление для запроса. Модели без мышления его не учитывают. |
GET /v1/models | Кроме id и owned_by: context_window и max_output_tokens (в токенах), capabilities (streaming, tools, forced_tool_choice, json_mode, vision, files, audio, reasoning, reasoning_effort, temperature, prompt_caching) и для моделей — pricing за 1 млн токенов (USD, а при включённой оплате и рубли). Для режима маршрутизации — наибольшие окно и ответ среди его моделей и то, что умеет хотя бы одна из них. Вложения: vision (картинки), files (PDF) и audio. |
400 context_length_exceeded | Разговор не помещается ни в одну доступную модель (или так ответил провайдер): в error.message — оценка и самое большое окно. Сократите историю или max_tokens; повтор того же запроса не поможет. |
error.retry_after, error.status | Сколько секунд подождать (ограничения частоты) — в каждой ошибке с Retry-After. Ошибка внутри потока (ответ уже начался с кодом 200) также содержит HTTP-статус, которому она соответствует. |
Limits | До 500 сообщений (настройка оператора MAX_MESSAGES_PER_REQUEST) и 128 инструментов в запросе, как в OpenAI API. |
Ошибки и лимиты запросов
Ошибки возвращаются в формате OpenAI {"error": {"message", "type", "code", "param", "request_id"}}, поэтому SDK выбрасывают привычные классы исключений, а по code видно, что произошло. Ошибки, после которых нужно подождать, содержат retry_after (в секундах).
| HTTP | code | Значение | Что делать |
|---|---|---|---|
| 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 | Некорректный или неподдерживаемый запрос: изображения на входе, json_schema, устаревшие functions, n > 1 — или провайдер отклонил запрос. | Исправьте запрос. Повтор не поможет. |
| 401 | missing_api_keyinvalid_api_keyapi_key_revokedapi_key_expired | Ключ не передан, неизвестен, отозван или истёк. | Передайте Authorization: Bearer aictrlx_live_…; если ключ отозван или истёк, создайте новый. |
| 403 | project_inactiveaccount_disabledmodel_not_allowed | Проект ключа деактивирован, аккаунт заблокирован или запрошенной модели либо режима маршрутизации нет среди разрешённых для ключа. | Снова активируйте проект на странице «Проекты»; используйте модель, разрешённую для ключа (их список возвращает GET /v1/models). |
| 404 | model_not_found | Значение model — не режим маршрутизации и не id модели из реестра. | Укажите auto, fast, smart, coding или id из GET /v1/models. |
| 429 | rate_limit_exceededupstream_rate_limited | Превышен поминутный лимит ключа, или все провайдеры-кандидаты ограничили частоту запросов. | Подождите error.retry_after (= Retry-After) секунд и повторите запрос. OpenAI SDK делают это автоматически. |
| 429 | monthly_quota_exceededdaily_quota_exceededproject_budget_exceededkey_budget_exceeded | Тип ошибки insufficient_quota: исчерпан кредит платформы, месячный бюджет проекта или месячный бюджет ключа. | Повтор не поможет до начала нового периода; владелец может увеличить или снять бюджет. |
| 502 | upstream_error | Все кандидаты маршрутизации завершились ошибкой (после повторов и переключения на резервные модели). | Повторите запрос с нарастающей задержкой. |
| 503 | no_routing_candidatesmodel_unavailablerate_limiter_unavailable | Ни одна доступная модель не может обработать запрос (например, нужны инструменты или режим JSON либо не настроен ни один провайдер), запрошенная модель недоступна или временно не работает ограничение частоты запросов. | Проверьте страницу «Модели»; попробуйте другой режим или модель. |
| 504 | upstream_timeout | Истекло время ожидания ответа провайдера для всех кандидатов. | Повторите запрос, уменьшите max_tokens или используйте режим fast. |
Лимиты запросов. У каждого API-ключа есть лимит запросов в минуту (скользящее окно 60 секунд); каждый ответ сообщает его в X-RateLimit-Limit и X-RateLimit-Remaining. При превышении лимита вы получите 429 с Retry-After в секундах. OpenAI SDK по умолчанию дважды повторяют запросы при ответах 429 и 5xx и учитывают Retry-After.
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
Те же ключи, режимы маршрутизации и модели работают и через POST /v1/messages, поэтому этот экземпляр можно использовать из официальных SDK anthropic и Claude Code. Передавайте ключ в x-api-key или Authorization: Bearer. Базовый URL для SDK — https://aictrlx.ru (без /v1): SDK сами добавляют /v1/messages.
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/completionsClaude Code
Направьте Claude Code на этот экземпляр и сопоставьте его уровни моделей с режимами маршрутизации (подойдёт и любой id модели из списка выше):
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Через этот метод API не поддерживаются: изображения и документы на входе, серверные инструменты (веб-поиск, выполнение кода), mcp_servers и вывод расширенного мышления (extended thinking). Неизвестные имена моделей Claude отклоняются, если оператор не сопоставил их с моделями через MESSAGES_API_MODEL_ALIASES.
Интеграции
Подойдёт любой инструмент, в котором можно указать базовый URL OpenAI-совместимого API. Используйте базовый URL, указанный выше, и свой ключ.
Cursor
- Откройте Cursor Settings → Models.
- В разделе API Keys вставьте ключ в поле OpenAI API Key и включите его.
- Включите Override OpenAI Base URL и укажите
https://aictrlx.ru/v1. - Добавьте пользовательские модели с именами
auto,smart,coding(или любым id модели из списка выше) и выберите одну из них в чате.
Cursor отправляет эти запросы со своих серверов, поэтому базовый URL должен быть доступен из интернета. Автодополнение по Tab по-прежнему использует встроенные модели Cursor.
Continue
Добавьте модели в ~/.continue/config.yaml (провайдер openai с параметром apiBase), подставив свой ключ вместо заглушки:
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
pip install langchain-openaiimport 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 answeredVercel AI SDK
Используйте createOpenAI с baseURL и фабрику моделей .chat(): этот API реализует Chat Completions, а не Responses API.
npm install ai @ai-sdk/openaiimport { 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 answeredLiteLLM
Добавьте к имени модели префикс openai/ (универсальный OpenAI-совместимый провайдер) и укажите api_base.
pip install litellmimport 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)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