# AgentAPI

AgentAPI — единый шлюз к 300+ AI-моделям. Один ключ, один базовый URL, оплата в рублях.
API совместим с форматом OpenAI, поэтому большинство существующих клиентов, SDK и плагинов
для редакторов работают без изменений в коде — достаточно поменять `base_url` и ключ.

## Что нужно знать сразу

| | |
|---|---|
| **Base URL** | `https://api.agentapi.ru/v1/ai` |
| **Аутентификация** | `x-api-key: agentapi-…` или `Authorization: Bearer agentapi-…` |
| **Формат ключа** | `agentapi-` + 48 hex-символов |
| **Форматы API** | OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Embeddings |
| **Модели** | формат `провайдер/модель` — `openai/gpt-4.1`, `anthropic/claude-3.5-sonnet` |
| **Оплата** | предоплаченный баланс в рублях, списание по факту токенов |
| **Swagger** | [api.agentapi.ru/v1/docs](https://api.agentapi.ru/v1/docs) |

> Обратите внимание на сегмент `/ai` в базовом URL — он обязателен.
> `https://agentapi.ru/v1` (без `api.` и без `/ai`) не существует: основной домен отдаёт сайт.

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

```bash
curl https://api.agentapi.ru/v1/ai/chat/completions \
  -H "x-api-key: agentapi-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'
```

Подробнее — [Быстрый старт](https://agentapi.ru/docs/quickstart).

## Контракт запроса

```mermaid
flowchart TD
    A["POST /v1/ai/chat/completions<br/>ключ + model + messages"] --> B{"stream?"}

    B -- "нет" --> C["200 · application/json<br/>текст в choices.message.content"]
    B -- "да" --> D["200 · text/event-stream<br/>SSE-кадры, финал DONE"]

    A -.-> E["401 · проблема с ключом"]
    A -.-> F["400 · параметры или баланс"]
    A -.-> G["429 · превышен лимит запросов"]
    A -.-> H["502 · модель недоступна"]
```

Что важно учесть на стороне клиента:

- **Ключ передаётся заголовком** — `x-api-key` или `Authorization: Bearer`, оба варианта
  равнозначны. См. [Аутентификация](https://agentapi.ru/docs/authentication).
- **Ключ показывается один раз** при создании и не может быть восстановлен. См.
  [API-ключи](https://agentapi.ru/docs/api-keys).
- **Стриминг завершается литералом `data: [DONE]`.** Ошибка, случившаяся после начала потока,
  приходит отдельным кадром при уже отданном статусе 200 — проверяйте поле `error` в каждом кадре.
- **Расход списывается с баланса в рублях по факту использованных токенов.** См.
  [Биллинг](https://agentapi.ru/docs/billing).

## Совместимость

Один и тот же аккаунт и ключ работают через четыре формата запроса:

| Формат | Эндпоинт | Кому подходит |
|---|---|---|
| OpenAI Chat Completions | [`POST /v1/ai/chat/completions`](https://agentapi.ru/docs/endpoints/chat-completions) | OpenAI SDK, Continue, Cline, Roo Code, LangChain |
| Anthropic Messages | [`POST /v1/ai/messages`](https://agentapi.ru/docs/endpoints/messages) | Anthropic SDK и клиенты Claude |
| OpenAI Responses | [`POST /v1/ai/responses`](https://agentapi.ru/docs/endpoints/responses) | клиенты на Responses API |
| Embeddings | [`POST /v1/ai/embeddings`](https://agentapi.ru/docs/endpoints/embeddings) | векторный поиск, RAG |

Настройка редакторов и плагинов:
[Continue](https://agentapi.ru/docs/integrations/continue) ·
[Cline](https://agentapi.ru/docs/integrations/cline) ·
[Roo Code](https://agentapi.ru/docs/integrations/roo-code) ·
[Claude Code](https://agentapi.ru/docs/integrations/claude-code) ·
[SDK и curl](https://agentapi.ru/docs/integrations/sdk)

## Дальше

1. [Быстрый старт](https://agentapi.ru/docs/quickstart) — первый запрос за 5 минут.
2. [API-ключи](https://agentapi.ru/docs/api-keys) — как создать, где хранить, как отозвать.
3. [Аутентификация](https://agentapi.ru/docs/authentication) — заголовки и ошибки 401.
4. [Модели](https://agentapi.ru/docs/models) — какие слаги использовать.
5. [Ошибки и лимиты](https://agentapi.ru/docs/errors) — коды ответов и rate limit.
6. [Известные ограничения](https://agentapi.ru/docs/limitations) — что пока не поддерживается.