Документация API

OpenAI-совместимый REST API · Base URL: https://api-ru.agi-iri.ru/v1/

Введение

IRI Gateway — единый шлюз с пятью продуктовыми уровнями и точным выбором доступной модели. API полностью совместим с OpenAI: меняете base_url и api_key в любом OpenAI-клиенте — и всё работает. Шлюз сам маршрутизирует запрос, делает failover при сбое и считает стоимость.

Быстрый старт

1. Зарегистрируйтесь и пополните баланс в кабинете.
2. Создайте API-ключ (формат vsk_live_…).
3. Укажите base_url=https://api-ru.agi-iri.ru/v1/ и ключ в клиенте — как для OpenAI.
4. Отправьте первый запрос (пример ниже) или вставьте ключ в Verstak.

Аутентификация

Все запросы — с заголовком Authorization: Bearer <ключ>. Ключ создаётся в кабинете и показывается один раз. Храните его как пароль: не коммитьте в репозиторий, не передавайте в prompt.

Базовый URL

Совместим с OpenAI SDK (Python, JS), curl и любым OpenAI-compatible клиентом.

Уровни Gateway

Для большинства задач не нужно выбирать конкретную модель. Укажите уровень в поле model, и Gateway подберёт рабочий маршрут с резервом:

Прежние имена уровней (verstak/free, verstak/start, verstak/pro, verstak/premium, verstak/ultra) по-прежнему принимаются и работают как iri-zero, iri-live, iri-galileo, iri-atlas, iri-prometheus.

Для полного контроля укажите точный id модели из актуального ответа GET /v1/models. Рыночный каталог — отдельный справочник: не каждая его позиция доступна через API.

Тиры и цены

Модели разделены на тиры. Цены — за 1M токенов в рублях, видны в каталоге.

Chat Completions

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="vsk_live_ВАШ_КЛЮЧ",
    base_url="https://api-ru.agi-iri.ru/v1/",
)

resp = client.chat.completions.create(
    model="iri-live",
    messages=[{"role": "user", "content": "Привет!"}],
)
print(resp.choices[0].message.content)

curl https://api-ru.agi-iri.ru/v1/chat/completions \
  -H "Authorization: Bearer vsk_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "iri-live",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "vsk_live_ВАШ_КЛЮЧ",
  baseURL: "https://api-ru.agi-iri.ru/v1/",
});

const resp = await client.chat.completions.create({
  model: "iri-live",
  messages: [{ role: "user", content: "Привет!" }],
});
console.log(resp.choices[0].message.content);

Параметры

Route modes

Поле route в теле запроса задаёт, что для вас важнее: стабильность, отказоустойчивость, цена, скорость или качество ответа. Шлюз подберёт путь под выбранный приоритет. Актуальный список — в GET /v1/routes.

Значения fast и quality устарели: они по-прежнему принимаются и не сломают интеграцию, но работают как обычный режим. Вернём их, когда сможем опереться на настоящие замеры скорости и качества, а не обещать по догадке.

Пример с явным режимом. Поле route — необязательное: без него шлюз выбирает путь сам, и это подходит большинству.

{
  "model": "iri-live",
  "route": "balanced",
  "messages": [
    {"role": "user", "content": "Привет"}
  ]
}

Список моделей

Возвращает единственный источник текущей доступности: пять уровней Gateway и точные модели, которые можно указать в запросе прямо сейчас. Каталог рынка служит для сравнения и может содержать недоступные позиции.

Использование

Статистика расхода по ключу: токены, запросы, стоимость. Детальные логи — в кабинете.

IRI Щит на компьютере

Щит — локальный фильтр персональных данных: он встаёт между вашим инструментом (Claude Code, Codex, Cursor, любой OpenAI-совместимый клиент) и сервером модели, маскирует структурные ПДн на выходе и возвращает их на входе. Модель и подписка остаются ваши — Щит ничего не подменяет, кроме значений в запросе.

Ключ тот же. Отдельной сущности нет: любой ваш ключ vsk_live_… подходит для Щита. Цена — 1 копейка за защищённый запрос, списывается с этого же баланса раз в сутки одним отчётом.

pip install -e shield
iri-shield key set vsk_live_…
iri-shield install claude-code
iri-shield doctor

Без ключа Щит работает и защищает — просто не ведёт учёт. При нулевом балансе он тоже продолжает маскировать и только напоминает о пополнении: фильтр не выключается из-за денег.

Отчёт Щита за сутки. Идемпотентен по (ключ, день, установка): повтор с тем же числом не списывает ничего, с большим — досписывает разницу. Отвечает 200 всегда, поле status — ok / low_balance / no_balance.

{ "day": "2026-09-07", "protected_requests": 50,
  "client": "iri-shield/0.2.0", "install_id": "…" }

Метадата ответа

Стандартный usage (токены) + блок verstak со стоимостью в рублях:

{
  "usage": { "prompt_tokens": 123, "completion_tokens": 456, "total_tokens": 579 },
  "verstak": {
    "cost_rub": 0.84,
    "balance_rub": 923.10,
    "route": { "preset": "iri-live", "provider": "deepseek" }
  }
}

Потоковый ответ

С "stream": true ответ приходит частями в формате Server-Sent Events, как у OpenAI: строки data: {...} с фрагментами текста и завершающая data: [DONE]. В OpenAI SDK достаточно передать stream=True и читать фрагменты в цикле.

stream = client.chat.completions.create(
    model="iri-live",
    messages=[{"role": "user", "content": "Напиши план статьи"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Если ошибка случилась уже после начала потока, она приходит отдельным событием data: {"error": {...}} в том же формате, что и обычная ошибка (см. ниже). Обрабатывайте его так же, как ответ с кодом ошибки.

Изображения в запросе

Картинку передают в сообщении пользователя как часть content в формате OpenAI — блок image_url со встроенными данными (data URL):

{
  "model": "iri-live",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Что на скриншоте?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0..." } }
    ]
  }]
}

• форматы — PNG, JPEG, WEBP; до 4 картинок в одном запросе, каждая до 5 МБ;
• принимаются только встроенные данные (data URL); ссылки на внешние файлы не принимаются;
• модель должна понимать изображения — иначе ответ 422 с типом image_input_unsupported_model. Какие модели работают с картинками — в каталоге.

Формат Anthropic: /v1/messages

Для программ, которые работают с API Anthropic (например, Claude Code), Gateway принимает тот же формат: POST /v1/messages с полями model, system, messages, max_tokens, инструментами и потоковой отдачей. Ключ и баланс — те же. Подключение Claude Code пошагово — в инструкции.

Ошибки

Ошибка приходит с HTTP-кодом и телом в формате OpenAI:

{
  "error": {
    "message": "Модель gpt-4-old снята, используйте …",
    "type": "model_retired"
  }
}

Ориентируйтесь на type (и code, если он есть), а не только на HTTP-код: под одним кодом бывают разные причины.

Повторять имеет смысл запросы с кодами 429 и 503 — с паузой. Остальные ошибки повтор не исправит: нужно изменить запрос, ключ или баланс.

Лимиты

На каждый ключ можно задать лимиты в кабинете: запросов в минуту, дневной и месячный потолок расхода, список разрешённых моделей. Бесплатный режим IRI Zero работает на доступной бесплатной вычислительной ёмкости; актуальные условия — в кабинете.

Личный кабинет

В кабинете: баланс и пополнение по счёту на р/с, API-ключи, логи запросов, расходы. Для бизнеса — договор, закрывающие, ЭДО, 152-ФЗ.

Verstak — интеграция

Verstak — десктоп-машина задачи поверх шлюза. Настройки → Провайдеры → Verstak Gateway → вставьте ключ → выберите пресет. Запросы пойдут через ваш рублёвый баланс.

Помощь

Потоковый ответ, изображения на входе и формат Anthropic — в разделах выше. Эмбеддингов в Gateway пока нет. Вопросы: форма связи