# Документация для разработчиков API KovAPI

OpenAI-compatible AI API gateway. Base URL: `https://kovapi.com/v1`

## Аутентификация
Каждый запрос содержит Bearer-токен:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Модели и цены
| Модель | Возможности | Эндпоинт | Цена |
| --- | --- | --- | --- |
| gpt-5.6-sol | Рассуждения переднего края, агентное программирование, долгосрочные задачи, структурированный вывод | /chat/completions | in $1.2/1M · out $6.0/1M |
| gpt-5.6-luna | Быстрый чат, агентное программирование, большие объёмы с низкой задержкой, структурированный вывод | /chat/completions | in $0.07/1M · out $0.4/1M |
| gpt-6-astra | Глубокое рассуждение, агентное программирование, очень длинный контекст, ввод изображений, структурированный вывод | /chat/completions | in $3.0/1M · out $15.0/1M |
| gpt-6.1-sol | Агентное программирование, сложное программирование, профессиональная работа с документами и аналитикой, рассуждение, очень длинный контекст, ввод изображений, структурированный вывод | /chat/completions | in $0.6/1M · out $3.0/1M |
| gpt-6-sol | Сложное программирование, агентные сценарии, рассуждение, очень длинный контекст, ввод изображений, структурированный вывод | /chat/completions | in $0.6/1M · out $3.0/1M |
| gpt-6-luna | Высоконагруженный чат, агентные шаги с низкой задержкой, классификация и извлечение данных, очень длинный контекст, структурированный вывод | /chat/completions | in $0.07/1M · out $0.4/1M |
| gpt-image-2 | Генерация изображений из текста, редактирование изображений (по изображению), обложки, постеры, иллюстрации | /images/generations | 1K $0.005 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | Генерация изображений из текста, редактирование изображений (по изображению), обложки, постеры, иллюстрации, типографика | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.5-sunburst | Генерация изображений из текста, редактирование изображений (по изображению), обложки, постеры, иллюстрации, типографика | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| nano-banana-2 | Текст в изображение, изображение в изображение, обложки, постеры, иллюстрации | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-pro | Текст в изображение, изображение в изображение, обложки, постеры, иллюстрации, инфографика | /images/generations | 1K $0.02 · 2K $0.03 · 4K $0.05 |
| nano-banana-2.1 | Генерация по тексту, редактирование, композиция из нескольких изображений, постеры и инфографика, фото товаров, широкие баннеры | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| grok-imagine-image | Генерация по тексту, редактирование, постеры, фото товаров, визуалы для соцсетей, надписи на китайском и английском | /images/generations | 1K $0.005 · 2K $0.005 |
| grok-imagine-image-quality | Обложки, постеры, фото товаров, иллюстрации, генерация по тексту и редактирование | /images/generations | 1K $0.01 · 2K $0.01 |
| claude-sonnet-4-6 | Чат, код, рассуждение, длинный контекст | /chat/completions | in $1.5/1M · out $7.5/1M |
| claude-opus-5 | Глубокое рассуждение, код, агенты, длинный контекст, распознавание изображений | /chat/completions | in $4.0/1M · out $20.0/1M |
| claude-fable-5 | Письмо на китайском, создание нарратива, генерация объёмных текстов, чат, код, распознавание изображений | /chat/completions | in $8.0/1M · out $40.0/1M |
| claude-opus-5-5 | Сложные рассуждения, длительное агентное программирование, инженерия кода, вызов инструментов, понимание изображений и PDF | /chat/completions | in $2.5/1M · out $12.5/1M |
| claude-sonnet-5-5 | Повседневное программирование и агенты, длинный контекст, вызов инструментов, понимание изображений и PDF, производственный трафик в больших объёмах | /chat/completions | in $1.5/1M · out $7.5/1M |
| gemini-4-argon | Beta · рассуждение · длинный контекст | /chat/completions | in $0.5/1M · out $3.0/1M |
| gemini-3.1-pro | Чат, рассуждение, очень длинный контекст, мультимодальность | /chat/completions | in $0.5/1M · out $3.0/1M |
| gemini-3.8-flash | Чат, рассуждение, адаптивное мышление, ввод изображений, очень длинный контекст | /chat/completions | in $0.6/1M · out $3.6/1M |
| deepseek-v4.1-flash | Чат, рассуждение, программирование, вызов инструментов, переключаемый режим рассуждения | /chat/completions | in $0.075/1M · out $0.3/1M |
| deepseek-v4-flash-0731 | Чат, рассуждение, программирование, вызов инструментов, переключаемый режим рассуждения, зафиксированная версия | /chat/completions | in $0.13/1M · out $0.51/1M |
| glm-5.3 | Чат, программирование, агентные сценарии, рассуждение, письмо на китайском и английском, вызов инструментов | /chat/completions | in $1.12/1M · out $3.52/1M |
| qwen3.8-max | Рассуждение, код, агенты и вызов функций, написание текстов на китайском и английском, понимание изображений | /chat/completions | in $1.4/1M · out $4.2/1M |
| qwen3.8-flash | Массовый чат, классификация и извлечение данных, суммаризация и переписывание, понимание изображений и OCR, вызов функций | /chat/completions | in $0.1/1M · out $0.33/1M |
| grok-4.7 | Сложные рассуждения, программирование, анализ длинных документов, вызов инструментов, структурированный вывод, распознавание изображений | /chat/completions | in $0.3/1M · out $0.9/1M |
| veo-3.1 | Короткие ролики, анимация товаров, переходы между кадрами, коммерческие ролики | /videos/generations | $0.2 / clip |
| gemini-omni-flash | Ролики из нескольких планов, сюжет по раскадровке, переходы между кадрами | /videos/generations | $0.05 / s (6-10s, billed per second) |
| seedance-2.5-token | Текстовые, графические, видео- и аудиореференсы | /videos/generations | USD / 1M video tokens: 480p/720p $10.2 ($6.1 with reference video); 1080p $11.1 ($6.7 with reference video). |
| seedance-2.5-token-draft | Текстовые, графические, видео- и аудиореференсы | /videos/generations | USD / 1M video tokens: 480p draft $10.2 ($6.1 with reference video). Upgrade billed separately. |
| seedance-2.5 | Короткие ролики одним длинным кадром, несколько референсов на входе, коммерческая съёмка | /videos/generations | $0.158 / s (4-30s, billed per second) |
| seedance-2.0 | Короткие ролики, коммерческие материалы | /videos/generations | $0.15 / s (5-15s, billed per second) |
| seedance-2.0-fast | Массовое производство материалов, быстрая проверка концепций | /videos/generations | $0.075 / s (5-15s, billed per second) |
| seedance-2.0-mini | Массовые черновики, недорогие итерации | /videos/generations | $0.046 / s (5-15s, billed per second) |
| seedance-2.0-clip | Короткие ролики с реальными людьми, товарные видео, пакетное производство | /videos/generations | $1.0 / clip |
| seedance-2.5-30s | Сюжетные видео одним длинным планом, длинные продуктовые ролики | /videos/generations | $2.0 / clip |
| wan3.0-video | Съёмка длинным планом, композиция из нескольких материалов, переработка видео | /videos/generations | $0.065 / s (4-30s, billed per second) |
| wan3.0-video-prime | Срочные материалы к дедлайну, пакетные тест-съёмки | /videos/generations | $0.112 / s (4-30s, billed per second) |
| minimax-h3 | HD-видео, короткие ролики со звуком | /videos/generations | $0.036 / s (5-15s, billed per second) |
| grok-imagine-video-1.5 | Массовая генерация коротких видео, быстрая проверка концепций | /videos/generations | $0.3 / clip |

## Чат (Chat Completions)
`POST /v1/chat/completions`; для потокового вывода передайте `stream: true`.
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```
Ввод изображения (распознавание изображений): добавьте `image_url` в массив `content` объекта `messages` — подойдёт публичная ссылка на изображение или base64 data URL:
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":[{"type":"text","text":"Что изображено на этой картинке?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## Изображения — асинхронные задачи (отправка возвращает ID задачи)
Эндпоинты изображений работают **только через задачи**: при отправке сразу возвращается `HTTP 202` и `id` задачи (`{"id":"img_...","object":"image.generation.job","status":"queued"}`); опрашивайте `GET /v1/images/jobs/{id}`, пока `status` не станет `succeeded`, и читайте `data[0].url` (ссылка на `img.kovapi.com`, хранится 15 дней; скачайте её или скопируйте в своё хранилище). **Не** ожидайте `data` в ответе на отправку.
**Текст в изображение** — это `POST /v1/images/generations`. **Изображение в изображение** — это `POST /v1/images/edits`, либо просто добавьте `image` к generations — оба варианта эквивалентны; `image` принимает публичный URL, `data:` URI или base64.
```bash
# 1) отправка -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"gpt-image-2","prompt":"a poster","size":"2:3"}'
# 2) опрашивайте каждые 2-3s, пока status=succeeded; результат в data[0].url
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Чтобы задать соотношение сторон, передайте в `size` значение `1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9` — модель отрендерит **нативно** именно в этом соотношении, без обрезки объекта; также принимаются размеры в пикселях (`1024x1024` / `1024x1536` / `1536x1024`). Это работает и для «Текст в изображение», и для «Изображение в изображение». Поле `async` больше не нужно и игнорируется, если его передать.


## Видео — асинхронные задачи (отправка возвращает ID задачи)
Видео тоже работает через задачи: `POST /v1/videos/generations` сразу возвращает `HTTP 202` и ID задачи (`{"id":"img_...","object":"video.generation.job","status":"queued"}`); опрашивайте `GET /v1/videos/jobs/{id}`, пока `status` не станет `succeeded`, и читайте `data[0].url` (ссылка на mp4, перезалитый на наш хостинг; хранится 15 дней). Клип рендерится от одной до нескольких минут (длинные клипы — дольше). Большинство моделей берут плату за секунду видео, некоторые — за клип целиком — тарифы указаны в таблице выше; за неудачную задачу — полный возврат. `size` задаёт соотношение сторон (по умолчанию `16:9`, альбомная ориентация; `9:16` — портретная); для «изображение в видео» передайте референс первого кадра в `image`.
```bash
# 1) отправка -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"veo-3.1","prompt":"кот сёрфит на закате","size":"16:9","duration":"8s"}'
# 2) опрашивайте каждые 5s, пока status=succeeded; результат в data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Video models available: `veo-3.1`, `gemini-omni-flash`, `seedance-2.5-token`, `seedance-2.5-token-draft`, `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `seedance-2.0-clip`, `seedance-2.5-30s`, `wan3.0-video`, `wan3.0-video-prime`, `minimax-h3`, `grok-imagine-video-1.5`.
Shared parameters: `size` (or `aspect_ratio`) for orientation, `duration` for length, `resolution` for quality where the model supports it, and `image` / `images[]` for a reference frame, which makes it image-to-video. Supported durations and resolutions differ per model; the exact table for each is at `/docs/<model id>`, e.g. [/docs/veo-3.1](/veo-3.1).

## Нативный API Anthropic (Claude Code подключается напрямую)
Beyond the OpenAI-compatible route, Claude models also expose the **native Anthropic Messages API**. Point `ANTHROPIC_BASE_URL` in Claude Code (or any Anthropic SDK) at `https://kovapi.com/anthropic` and use your gateway key as `x-api-key` (`Authorization: Bearer` works too). Thinking, tool use and prompt caching all pass through unchanged. Models: claude-opus-5, claude-fable-5, claude-sonnet-4-6. Billed exactly like /v1, per token, cache reads and writes included.
```bash
export ANTHROPIC_BASE_URL=https://kovapi.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://kovapi.com/anthropic/v1/messages -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
`"stream": true` поддерживается как стандартный Anthropic SSE (message_start / content_block_delta / message_delta / message_stop), а также `/anthropic/v1/messages/count_tokens` и `GET /anthropic/v1/models`.
**Оплата кэширования промптов**: попадание в кэш (чтение кэша) оплачивается по **1/10** от цены ввода (0.1x), а запись в кэш — по **1.25x** (тарифы по каждой модели — на [странице цен](https://kovapi.com/pricing)). Для попадания нужны три условия: побайтово идентичный префикс, достаточно длинный (Claude Opus >= 4096 токенов, Sonnet >= 2048), и повтор того же префикса в течение короткого окна. Claude Code с большим `CLAUDE.md` или системным промптом поверх реального кода проекта попадает в кэш при каждом обращении и платит примерно десятую часть за ввод; короткие обмены в Песочнице слишком малы для кэширования — это ожидаемо.

## Проверка баланса
Проверить баланс и расход по аккаунту может любой API-ключ — вход в панель управления не нужен:
```bash
curl https://kovapi.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
Совместимый с OpenAI вариант (баланс = `total_available`, поэтому обычные инструменты проверки баланса подхватывают его автоматически):
```bash
curl https://kovapi.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Коды ошибок
| HTTP | Когда возникает |
| --- | --- |
| 400 | Неверный параметр или неизвестная модель (например, `model_not_found`); `error.param` указывает на поле. |
| 401 | Нет ключа, или он недействителен либо отключён (`missing_api_key`, `invalid_api_key`). |
| 402 | Недостаточно средств или ключ исчерпал свой бюджет (`insufficient_quota`). |
| 403 | Модели нет в списке разрешённых моделей ключа, или запрос пришёл не с разрешённого для ключа IP (`permission_denied`). |
| 404 | Пути не существует, либо id задачи неизвестен, старше 3 дней хранения записи или задачу отправил другой аккаунт (`job_not_found`). |
| 429 | Превышен лимит запросов в минуту для этого ключа или дневная квота бесплатной модели, либо модель загружена до предела (`rate_limit_exceeded`). Подождите столько секунд, сколько указано в `Retry-After`, а если его нет — несколько секунд, и повторите. |
| 502 | Ошибка или таймаут на стороне поставщика, и автоматические повторы не помогли; причина в `code`, например `upstream_timeout` или `upstream_unavailable`. Запрос не оплачивается, его можно повторить. |
| 503 | Модель на обслуживании (`model_maintenance`) или на нашей стороне произошёл кратковременный сбой (`service_unavailable`). Запрос не оплачивается; повторите позже. |

Полный список кодов ошибок: https://docs.kovapi.com/ru/guide/errors/md