# API ИИ-адаптер (api.aiadapter.ru) — справочник для AI-агентов

ИИ-адаптер — единый API ко всем ИИ-моделям, **OpenRouter/OpenAI-совместимый**, оплата в рублях. Чтобы перейти с OpenAI/OpenRouter, достаточно поменять base_url и api_key.

- **Base URL:** `https://api.aiadapter.ru/api/v1`
- **Авторизация:** заголовок `Authorization: Bearer sk-aa-v1-...` (ключ создаётся в личном кабинете https://lk.aiadapter.ru).
- **Стриминг:** добавьте `"stream": true` — ответ придёт строками `data: {…}`, завершаясь `data: [DONE]`.
- **Стоимость запроса:** передайте `"usage": {"include": true}` — в `usage.cost_rub` ответа вернётся цена в рублях.

## Ошибки

Формат: `{ "error": { "message": "...", "type": "...", "code": "..." } }`

| code | HTTP | значение |
|---|---|---|
| `no_auth` | 401 | Заголовок Authorization отсутствует |
| `invalid_api_key` | 401 | Ключ не найден или неверный формат |
| `key_disabled` | 403 | Ключ отключён в личном кабинете |
| `key_expired` | 403 | Истёк срок действия ключа |
| `insufficient_balance` | 402 | Недостаточно средств на балансе |
| `key_limit_reached` | 402 | Достигнут лимит расхода по ключу |
| `model_not_allowed` | 403 | Модель недоступна на шлюзе (free / служебная) |
| `endpoint_not_found` | 404 | Эндпоинт не поддерживается шлюзом |
| `bad_gateway` | 502 | Ошибка вышестоящего провайдера |

## Методы

### Текстовые модели

#### POST /chat/completions — chat/completions (тарифицируется)

Генерация ответа в формате чата. Полностью совместимо с OpenAI Chat Completions. Поддерживает стриминг (SSE), вызов инструментов, vision и генерацию картинок.

Параметры тела:
- `model` (string) **required** — Модель. Идентификатор из каталога, напр. anthropic/claude-opus-4.8.
- `messages` (array) **required** — Сообщения. Список сообщений диалога: объекты {"role","content"}. role — system | user | assistant | tool.
- `stream` (boolean) — Стриминг. true → ответ потоком (SSE), токены по мере генерации.
- `temperature` — Температура. Управляет случайностью выбора следующего токена. Значение около 0 делает ответы почти детерминированными и предсказуемыми — модель каждый раз выбирает наиболее вероятное продолжение. Более высокие значения (0.7–1.0 и выше) повышают разнообразие и «креативность», но и риск ошибок и бессвязности. Для фактических задач и кода обычно берут низкую температуру, для генерации идей и текстов — выше.
- `max_tokens` — Лимит ответа. Ограничивает максимальное число токенов, которое модель сгенерирует в ответе. Это потолок длины именно ответа, не считая токенов запроса; сумма запроса и ответа не может превышать размер контекстного окна. Если лимит мал, ответ может оборваться на середине. Параметр также влияет на стоимость, так как выходные токены тарифицируются отдельно.
- `top_p` — Top-p (выборка ядра). Ограничивает выбор токенов наименьшим набором, суммарная вероятность которого не превышает значения p (nucleus sampling). Например, при 0.9 модель рассматривает только самые вероятные варианты, на которые приходится 90% вероятностной массы, отсекая «хвост» маловероятных. Это альтернативный температуре способ управлять разнообразием ответа. Обычно меняют либо температуру, либо top-p, а не оба параметра одновременно.
- `tools` — Инструменты. Описание набора функций (инструментов), которые модель может вызвать в ходе ответа. Для каждого инструмента передаётся имя, назначение и JSON-схема параметров. Модель сама решает, когда уместно вызвать инструмент, и возвращает имя функции с аргументами, а выполнение остаётся на стороне приложения. Это основа агентных сценариев и интеграций с внешними сервисами и данными.
- `tool_choice` — Выбор инструмента. Управляет тем, будет ли модель вызывать инструменты и какой именно. Режим auto оставляет решение модели, none запрещает вызовы, required заставляет вызвать хотя бы один инструмент. Можно жёстко указать конкретную функцию, которую нужно вызвать. Полезно, когда логика приложения требует предсказуемого поведения вместо свободного выбора модели.
- `response_format` — Формат ответа. Задаёт требуемый формат вывода модели. В режиме JSON-объекта модель обязана вернуть синтаксически корректный JSON, что удобно для программной обработки. Можно также потребовать соответствие конкретной JSON-схеме. Использование этого параметра снижает необходимость «вычищать» свободный текст и парсить его эвристиками.
- `stop` — Стоп-последовательности. Список строк, при появлении которых генерация немедленно останавливается. Сами стоп-строки в ответ не включаются, что удобно для обрезания вывода по разделителю или маркеру конца. Часто используется в структурированных промптах и при ролевой разметке диалога. Можно задать несколько последовательностей одновременно.
- `seed` — Зерно (seed). Фиксирует источник случайности генерации, чтобы при одинаковых запросе и параметрах получать максимально воспроизводимый результат. Полезно для отладки, тестов и сравнения настроек, когда нужна повторяемость. Полная детерминированность не гарантируется и зависит от инфраструктуры провайдера. Изменение seed при прочих равных даёт другой, но столь же стабильный вариант ответа.
- `reasoning` — Рассуждения. Включает режим внутренних пошаговых рассуждений модели перед выдачей финального ответа. Позволяет управлять «обдумыванием»: глубиной размышлений или бюджетом токенов на них. Как правило, повышает качество на сложных задачах — логике, математике, многошаговом планировании — ценой большего времени и стоимости. Сами рассуждения могут не показываться пользователю, если не запрошены отдельно.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.8","messages":[{"role":"user","content":"Привет!"}]}'
```

Тело запроса:

```json
{
  "model": "anthropic/claude-opus-4.8",
  "messages": [
    {
      "role": "user",
      "content": "Привет!"
    }
  ]
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-abc123",
  "object": "chat.completion",
  "model": "anthropic/claude-opus-4.8",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20,
    "cost_rub": 0.042
  }
}
```

> Стриминг: добавьте "stream": true — ответ придёт строками `data: {…}`, завершаясь `data: [DONE]`. Чтобы в финальном чанке вернулась стоимость `cost_rub`, передайте `"stream_options": {"include_usage": true}`.

#### POST /completions — completions (тарифицируется)

Классическое текстовое дополнение (legacy). Принимает строку prompt вместо массива сообщений.

Параметры тела:
- `model` (string) **required** — Модель. Идентификатор модели из каталога.
- `prompt` (string) **required** — Промпт. Текст, который модель продолжит.
- `max_tokens` — Лимит ответа. Ограничивает максимальное число токенов, которое модель сгенерирует в ответе. Это потолок длины именно ответа, не считая токенов запроса; сумма запроса и ответа не может превышать размер контекстного окна. Если лимит мал, ответ может оборваться на середине. Параметр также влияет на стоимость, так как выходные токены тарифицируются отдельно.
- `temperature` — Температура. Управляет случайностью выбора следующего токена. Значение около 0 делает ответы почти детерминированными и предсказуемыми — модель каждый раз выбирает наиболее вероятное продолжение. Более высокие значения (0.7–1.0 и выше) повышают разнообразие и «креативность», но и риск ошибок и бессвязности. Для фактических задач и кода обычно берут низкую температуру, для генерации идей и текстов — выше.
- `stop` — Стоп-последовательности. Список строк, при появлении которых генерация немедленно останавливается. Сами стоп-строки в ответ не включаются, что удобно для обрезания вывода по разделителю или маркеру конца. Часто используется в структурированных промптах и при ролевой разметке диалога. Можно задать несколько последовательностей одновременно.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/completions \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.8","prompt":"Жили-были"}'
```

Тело запроса:

```json
{
  "model": "anthropic/claude-opus-4.8",
  "prompt": "Жили-были"
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-def456",
  "object": "text_completion",
  "model": "anthropic/claude-opus-4.8",
  "choices": [
    {
      "index": 0,
      "text": " дед да баба…",
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 16,
    "total_tokens": 20,
    "cost_rub": 0.03
  }
}
```

#### POST /embeddings — embeddings (тарифицируется)

Векторные представления (эмбеддинги) текста — для поиска, кластеризации, RAG.

Параметры тела:
- `model` (string) **required** — Модель. Эмбеддинг-модель, напр. openai/text-embedding-3-small.
- `input` (string | array) **required** — Вход. Строка или массив строк для векторизации.
- `dimensions` (integer) — Размерность. Желаемая длина вектора (если модель поддерживает усечение).
- `encoding_format` (string) — Формат. float (по умолчанию) или base64.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/embeddings \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/text-embedding-3-small","input":"Привет, мир"}'
```

Тело запроса:

```json
{
  "model": "openai/text-embedding-3-small",
  "input": "Привет, мир"
}
```

Ответ (HTTP 200):

```json
{
  "object": "list",
  "model": "openai/text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 3,
    "total_tokens": 3,
    "cost_rub": 0.0008
  }
}
```

#### POST /messages — messages (тарифицируется)

Эндпоинт в формате Anthropic Messages. Удобно, если у вас уже есть код под Anthropic SDK — поменяйте base URL и ключ.

Параметры тела:
- `model` (string) **required** — Модель. Идентификатор модели из каталога.
- `max_tokens` (integer) **required** — Лимит ответа. Максимум токенов в ответе (в Anthropic-формате обязателен).
- `messages` (array) **required** — Сообщения. Массив сообщений {"role","content"}.
- `system` (string) — Системный промпт. Системная инструкция (отдельным полем, а не сообщением).
- `temperature` — Температура. Управляет случайностью выбора следующего токена. Значение около 0 делает ответы почти детерминированными и предсказуемыми — модель каждый раз выбирает наиболее вероятное продолжение. Более высокие значения (0.7–1.0 и выше) повышают разнообразие и «креативность», но и риск ошибок и бессвязности. Для фактических задач и кода обычно берут низкую температуру, для генерации идей и текстов — выше.
- `stream` (boolean) — Стриминг. Потоковый ответ (SSE).
- `tools` — Инструменты. Описание набора функций (инструментов), которые модель может вызвать в ходе ответа. Для каждого инструмента передаётся имя, назначение и JSON-схема параметров. Модель сама решает, когда уместно вызвать инструмент, и возвращает имя функции с аргументами, а выполнение остаётся на стороне приложения. Это основа агентных сценариев и интеграций с внешними сервисами и данными.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/messages \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.8","max_tokens":1024,"messages":[{"role":"user","content":"Привет!"}]}'
```

Тело запроса:

```json
{
  "model": "anthropic/claude-opus-4.8",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Привет!"
    }
  ]
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-msg789",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-opus-4.8",
  "content": [
    {
      "type": "text",
      "text": "Привет! Чем помочь?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 8,
    "output_tokens": 12,
    "cost_rub": 0.042
  }
}
```

#### POST /responses — responses (тарифицируется)

Эндпоинт в формате OpenAI Responses API — современная альтернатива chat/completions с полем input и встроенными инструментами.

Параметры тела:
- `model` (string) **required** — Модель. Идентификатор модели из каталога.
- `input` (string | array) **required** — Вход. Строка или массив элементов входа.
- `instructions` (string) — Инструкции. Системная инструкция для модели.
- `max_output_tokens` (integer) — Лимит ответа. Максимум токенов в ответе.
- `temperature` — Температура. Управляет случайностью выбора следующего токена. Значение около 0 делает ответы почти детерминированными и предсказуемыми — модель каждый раз выбирает наиболее вероятное продолжение. Более высокие значения (0.7–1.0 и выше) повышают разнообразие и «креативность», но и риск ошибок и бессвязности. Для фактических задач и кода обычно берут низкую температуру, для генерации идей и текстов — выше.
- `stream` (boolean) — Стриминг. Потоковый ответ (SSE).
- `tools` — Инструменты. Описание набора функций (инструментов), которые модель может вызвать в ходе ответа. Для каждого инструмента передаётся имя, назначение и JSON-схема параметров. Модель сама решает, когда уместно вызвать инструмент, и возвращает имя функции с аргументами, а выполнение остаётся на стороне приложения. Это основа агентных сценариев и интеграций с внешними сервисами и данными.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/responses \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.8","input":"Привет!"}'
```

Тело запроса:

```json
{
  "model": "anthropic/claude-opus-4.8",
  "input": "Привет!"
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-resp012",
  "object": "response",
  "model": "anthropic/claude-opus-4.8",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Привет! Чем помочь?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 12,
    "cost_rub": 0.042
  }
}
```

### Аудио/Видео

#### POST /videos — Генерация видео (тарифицируется)

Текст → видео. Асинхронно: POST создаёт задачу и возвращает её id, статус опрашивается через GET /videos/{id}, готовый файл — через GET /videos/{id}/content.

Параметры тела:
- `model` (string) **required** — Модель. Видео-модель, напр. minimax/video-01.
- `prompt` (string) **required** — Промпт. Текстовое описание сцены.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/videos \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax/video-01","prompt":"Кот играет на пианино"}'
```

Тело запроса:

```json
{
  "model": "minimax/video-01",
  "prompt": "Кот играет на пианино"
}
```

Ответ (HTTP 202):

```json
{
  "id": "gen-vid901",
  "status": "queued",
  "polling_url": "/api/v1/videos/gen-vid901",
  "usage": {
    "cost_rub": 63.2
  }
}
```

#### POST /chat/completions — Генерация изображений (тарифицируется)

Текст → картинка. Тоже через /chat/completions: укажите модель с output-модальностью «Изображения» и попросите сгенерировать изображение. Картинка возвращается в ответе.

Параметры тела:
- `model` (string) **required** — Модель. Модель с output-модальностью «Изображения» (см. каталог).
- `messages` (array) **required** — Сообщения. Текстовый запрос на генерацию изображения.
- `modalities` (array) — Модальности. Желаемые типы вывода, напр. ["image","text"].

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.5-flash-image","messages":[{"role":"user","content":"Нарисуй кота-космонавта"}],"modalities":["image","text"]}'
```

Тело запроса:

```json
{
  "model": "google/gemini-3.5-flash-image",
  "messages": [
    {
      "role": "user",
      "content": "Нарисуй кота-космонавта"
    }
  ],
  "modalities": [
    "image",
    "text"
  ]
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-img678",
  "model": "google/gemini-3.5-flash-image",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgo…"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 0,
    "total_tokens": 6,
    "cost_rub": 2.4
  }
}
```

#### POST /chat/completions — Изображение => Текст (тарифицируется)

Картинка → текст (vision). Это НЕ отдельный метод: передайте изображение в content сообщения как элемент image_url у обычного /chat/completions.

Параметры тела:
- `model` (string) **required** — Модель. Модель с input-модальностью «Изображения» (см. каталог).
- `messages` (array) **required** — Сообщения. content — массив частей: {"type":"text"} и {"type":"image_url","image_url":{"url":…}}. URL или data:base64.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.5-flash","messages":[{"role":"user","content":[{"type":"text","text":"Что изображено на картинке?"},{"type":"image_url","image_url":{"url":"https://example.com/cat.jpg"}}]}]}'
```

Тело запроса:

```json
{
  "model": "google/gemini-3.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Что изображено на картинке?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/cat.jpg"
          }
        }
      ]
    }
  ]
}
```

Ответ (HTTP 200):

```json
{
  "id": "gen-vis345",
  "model": "google/gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "На картинке кот."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 264,
    "completion_tokens": 8,
    "total_tokens": 272,
    "cost_rub": 0.18
  }
}
```

#### POST /audio/transcriptions — Речь => Текст (тарифицируется)

Речь → текст (STT). Принимает аудио (base64), возвращает расшифровку.

Параметры тела:
- `model` (string) **required** — Модель. STT-модель, напр. openai/gpt-4o-transcribe.
- `file` (string) **required** — Аудио. Аудиоданные в base64 (или multipart-загрузка).
- `language` (string) — Язык. ISO-код языка для повышения точности (опционально).

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-transcribe","file":"<base64-аудио>"}'
```

Тело запроса:

```json
{
  "model": "openai/gpt-4o-transcribe",
  "file": "<base64-аудио>"
}
```

Ответ (HTTP 200):

```json
{
  "text": "привет мир",
  "usage": {
    "input_tokens": 5,
    "seconds": 3,
    "total_tokens": 5,
    "cost_rub": 0.38
  }
}
```

#### POST /audio/speech — Текст => Речь (тарифицируется)

Текст → речь (TTS). Возвращает бинарный аудиопоток (audio/mpeg и т.п.). Тарифицируется по факту генерации.

Параметры тела:
- `model` (string) **required** — Модель. TTS-модель, напр. openai/gpt-4o-mini-tts.
- `input` (string) **required** — Текст. Текст для озвучивания.
- `voice` (string) **required** — Голос. Идентификатор голоса (зависит от модели), напр. alloy.
- `response_format` (string) — Формат. mp3 | opus | wav | pcm.
- `speed` (number) — Скорость. Скорость речи, напр. 1.0.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/audio/speech \
  -H "Authorization: Bearer sk-aa-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini-tts","input":"Привет!","voice":"alloy"}'
```

Тело запроса:

```json
{
  "model": "openai/gpt-4o-mini-tts",
  "input": "Привет!",
  "voice": "alloy"
}
```

Ответ: Бинарный аудиопоток (Content-Type: audio/mpeg). Сохраните тело ответа в файл .mp3.

### Каталог

#### GET /models — Список моделей

Список доступных моделей с ценами и характеристиками.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/models \
  -H "Authorization: Bearer sk-aa-v1-..."
```

Ответ (HTTP 200):

```json
{
  "data": [
    {
      "id": "anthropic/claude-opus-4.8",
      "name": "Claude Opus 4.8",
      "context_length": 200000,
      "pricing": {
        "prompt": "0.000003",
        "completion": "0.000015"
      },
      "architecture": {
        "input_modalities": [
          "text",
          "image"
        ],
        "output_modalities": [
          "text"
        ]
      }
    }
  ]
}
```

#### GET /providers — Провайдеры

Список провайдеров, доступных через шлюз.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/providers \
  -H "Authorization: Bearer sk-aa-v1-..."
```

Ответ (HTTP 200):

```json
{
  "data": [
    {
      "name": "Anthropic",
      "slug": "anthropic"
    }
  ]
}
```

### Аккаунт

#### GET /key — Информация о ключе

Информация о текущем ключе: лимит, израсходовано и остаток (в рублях).

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/key \
  -H "Authorization: Bearer sk-aa-v1-..."
```

Ответ (HTTP 200):

```json
{
  "data": {
    "label": "sk-aa-v1-AbCd…wXyZ",
    "limit": 1000,
    "usage": 123.45,
    "limit_remaining": 876.55,
    "is_free_tier": false,
    "rate_limit": {
      "requests": 200,
      "interval": "10s"
    }
  }
}
```

#### GET /credits — Баланс

Баланс аккаунта: всего пополнено и всего израсходовано (в рублях).

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/credits \
  -H "Authorization: Bearer sk-aa-v1-..."
```

Ответ (HTTP 200):

```json
{
  "data": {
    "total_credits": 5000,
    "total_usage": 1234.56
  }
}
```

#### GET /generation — Метаданные генерации

Метаданные и стоимость одной генерации по её id (id берётся из поля id в ответе на запрос). Доступны только ваши генерации.

Пример запроса:

```bash
curl https://api.aiadapter.ru/api/v1/generation?id=ID \
  -H "Authorization: Bearer sk-aa-v1-..."
```

Ответ (HTTP 200):

```json
{
  "data": {
    "id": "gen-abc123",
    "model": "anthropic/claude-opus-4.8",
    "total_cost_rub": 0.042,
    "tokens_prompt": 8,
    "tokens_completion": 12
  }
}
```