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

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

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

## Модели и цены
| Модель | Возможности | Эндпоинт | Цена |
| --- | --- | --- | --- |
| gpt-5.6-sol | Рассуждения переднего края, агентное программирование, долгосрочные задачи, структурированный вывод | /chat/completions | in $0.4/1M · out $2.0/1M |
| gpt-5.6-terra | Повседневный чат, агентное программирование, рассуждения, структурированный вывод | /chat/completions | in $0.2/1M · out $1.2/1M |
| gpt-5.6-luna | Быстрый чат, агентное программирование, большие объёмы с низкой задержкой, структурированный вывод | /chat/completions | in $0.07/1M · out $0.4/1M |
| gpt-5.5 | Чат, рассуждения, агенты, структурированный вывод | /chat/completions | in $0.5/1M · out $3.0/1M |
| gpt-6-astra | Глубокое рассуждение, агентное программирование, очень длинный контекст, ввод изображений, структурированный вывод | /chat/completions | in $1.0/1M · out $5.0/1M |
| gpt-6-sol | Сложное программирование, агентные сценарии, рассуждение, очень длинный контекст, ввод изображений, структурированный вывод | /chat/completions | in $0.2/1M · out $1.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.01 · 4K $0.02 |
| gpt-image-2.5-flare | Генерация изображений из текста, редактирование изображений (по изображению), обложки, постеры, иллюстрации, типографика | /images/generations | 1K $0.005 · 2K $0.01 · 4K $0.02 |
| gpt-image-2.5-sunburst | Генерация изображений из текста, редактирование изображений (по изображению), обложки, постеры, иллюстрации, типографика | /images/generations | 1K $0.005 · 2K $0.01 · 4K $0.02 |
| nano-banana-2 | Текст в изображение, изображение в изображение, обложки, постеры, иллюстрации | /images/generations | 1K $0.025 · 2K $0.0375 · 4K $0.0625 |
| nano-banana-pro | Текст в изображение, изображение в изображение, обложки, постеры, иллюстрации, инфографика | /images/generations | 1K $0.04 · 2K $0.06 · 4K $0.1 |
| 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 |
| 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 |
| gemini-3.7-flash | Чат, рассуждение, адаптивное мышление, ввод изображений, очень длинный контекст | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash | Чат, рассуждение, мышление, ввод изображений, очень длинный контекст | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-high | Глубокие рассуждения, сложные задачи, мышление, ввод изображений, очень длинный контекст | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-low | Быстрый чат, большие объёмы, низкая задержка, ввод изображений | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3.6-flash-tiered | Адаптивное мышление, чат, рассуждения, ввод изображений | /chat/completions | in $0.6/1M · out $3.6/1M |
| gemini-3-flash-preview | Чат, рассуждения, высокая параллельность, низкая задержка | /chat/completions | in $0.3/1M · out $1.2/1M |
| gemini-2.5-flash | Чат, высокая параллельность, низкая задержка, мультимодальность | /chat/completions | in $0.3/1M · out $1.2/1M |
| deepseek-v4.1-flash | Чат, рассуждение, программирование, вызов инструментов, переключаемый режим рассуждения | /chat/completions | in $0.09/1M · out $0.36/1M |
| deepseek-v4-flash-0731 | Чат, рассуждение, программирование, вызов инструментов, переключаемый режим рассуждения, зафиксированная версия | /chat/completions | in $0.045/1M · out $0.18/1M |
| glm-5.3 | Чат, программирование, агентные сценарии, рассуждение, письмо на китайском и английском, вызов инструментов | /chat/completions | in $0.34/1M · out $1.25/1M |
| glm-5.3-flash | Чат с высокой нагрузкой, классификация и извлечение данных, суммаризация и переписывание текста, вызов функций | /chat/completions | in $0.072/1M · out $0.25/1M |
| kimi-k3 | Понимание длинных документов, анализ нескольких документов, написание текстов на китайском, агенты и вызов функций, рассуждение | /chat/completions | in $1.8/1M · out $9.0/1M |
| qwen3.7-max | Рассуждение, код, агенты и вызов функций, написание текстов на китайском и английском, длинный контекст | /chat/completions | in $1.65/1M · out $4.85/1M |
| grok-4.7 | Сложные рассуждения, программирование, анализ длинных документов, вызов инструментов, структурированный вывод, распознавание изображений | /chat/completions | in $0.3/1M · out $0.9/1M |
| veo-3.1 | Текст в видео, изображение в видео, короткие ролики, коммерческие съёмки | /videos/generations | $0.075 / clip · скоро, пока нельзя вызвать |
| 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.5-30s | Сюжетные видео одним длинным планом, длинные продуктовые ролики | /videos/generations | $1.5 / clip |
| wan3.0-video | Съёмка длинным планом, композиция из нескольких материалов, переработка видео | /videos/generations | $0.12 / s (2-30s, billed per second) |
| wan3.0-video-prime | Срочные материалы к дедлайну, пакетные тест-съёмки | /videos/generations | $0.16 / s (2-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://nezhagate.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://nezhagate.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.nezhagate.com`, хранится 60 дней; скачайте её или скопируйте в своё хранилище). **Не** ожидайте `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://nezhagate.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://nezhagate.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, перезалитый на наш хостинг; хранится 60 дней). Клип рендерится от одной до нескольких минут (длинные клипы — дольше). Большинство моделей берут плату за секунду видео, некоторые — за клип целиком — тарифы указаны в таблице выше; за неудачную задачу — полный возврат. `size` задаёт соотношение сторон (по умолчанию `16:9`, альбомная ориентация; `9:16` — портретная); для «изображение в видео» передайте референс первого кадра в `image`.
```bash
# 1) отправка -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"seedance-2.5","prompt":"кот сёрфит на закате","size":"16:9","duration":"8s"}'
# 2) опрашивайте каждые 5s, пока status=succeeded; результат в data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Video models available: `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast`, `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/seedance-2.5](/docs/seedance-2.5).

## Нативный 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://nezhagate.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://nezhagate.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://nezhagate.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** (тарифы по каждой модели — на [странице цен](/pricing)). Для попадания нужны три условия: побайтово идентичный префикс, достаточно длинный (Claude Opus >= 4096 токенов, Sonnet >= 2048), и повтор того же префикса в течение короткого окна. Claude Code с большим `CLAUDE.md` или системным промптом поверх реального кода проекта попадает в кэш при каждом обращении и платит примерно десятую часть за ввод; короткие обмены в Песочнице слишком малы для кэширования — это ожидаемо.

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

## Коды ошибок
| Статус | Значение |
| --- | --- |
| 401 | API-ключ отсутствует или недействителен |
| 402 | Недостаточно баланса или ключ превысил лимит |
| 400 | Неподдерживаемая модель или параметр |
| 429 | Лимит запросов у вышестоящего провайдера |
| 502 | Ни один из вышестоящих маршрутов не сработал |