# Начало работы — neuraldeep.ru API

> Раздел машиночитаемой справки. Все разделы: https://neuraldeep.ru/llms.txt · всё одним файлом: https://neuraldeep.ru/llms-full.txt

Base URL: `https://api.neuraldeep.ru/v1`
Auth: `Authorization: Bearer $YOUR_KEY`

Все API платформы живут на одном адресе и принимают один ключ. Чат, эмбеддинги, реранк и транскрибация совместимы с OpenAI: подойдёт любой OpenAI SDK, достаточно поменять `base_url`. Поиск, OCR, картинки, музыка, озвучка и диаризация работают тем же ключом, у каждого свой раздел ниже.

| что | значение |
|---|---|
| базовый адрес | `https://api.neuraldeep.ru/v1` |
| авторизация | заголовок `Authorization: Bearer sk-...` |
| ключ | [кабинет, раздел «Ключи»](https://hub.neuraldeep.ru/app/keys) |
| каталог моделей ключа | `GET /v1/models` |
| витрина моделей и цены | [/models](https://hub.neuraldeep.ru/models) |

```bash
curl -s https://api.neuraldeep.ru/v1/models \
  -H "Authorization: Bearer $YOUR_KEY" | jq '.data[].id'
```

**Какие модели доступны вашему ключу.** `GET /v1/models` отдаёт модели ключа со свойствами (картинки, инструменты, рассуждение), окном контекста и ценой. Важная оговорка: ключ бесплатного тарифа пока видит в списке и модели платных тарифов, а вызов такой модели вернёт `403` с заголовком `X-Window: free-model`.

- На бесплатном тарифе работают `qwen3.6-35b-a3b`, `qwen3.6-fp8` и их `-noreason`-варианты, все эмбеддинги и реранкеры, транскрибация с небольшой дневной квотой.
- `gemma-4-31b`, `gemma-4-31b-noreason`, `gpt-oss-120b`, `gpt-oss-20b`, `qwen3.8-27b` и `qwen3.8-27b-noreason` доступны на платных тарифах и с кошелька по токенам.
- Ключ в режиме «Кошелёк» платит за каждый вызов по ценам витрины. Режим переключается у каждого ключа в кабинете. Пополнили кошелёк, а ключ остался в «Подписке» на free, значит, он по-прежнему живёт по правилам free.

**Формат ошибок.** Гейт моделей (чат, эмбеддинги, реранк, транскрибация) отвечает как OpenAI: `{"error": {"message": "...", "code": "429"}}`. Сервисы поиска, OCR, картинок, озвучки и диаризации отвечают `{"detail": "..."}`. Исчерпанная квота у сервисов приходит отдельным телом, оно ниже. Тексты ошибок приходят на русском или английском: по языку кабинета владельца ключа, иначе по заголовку `Accept-Language` запроса, иначе на русском.

| код | что значит | что делать |
|---|---|---|
| 400 | неверный запрос: битый JSON, нечитаемый файл, вход длиннее окна модели | исправить запрос, повтор не поможет |
| 401 | ключ неверный или отозван, либо модели нет в ключе | проверить ключ и имя модели |
| 402 | на кошельке нет денег для платной модели или операции (`X-Wallet: empty`), текст вида «Кошелёк пуст (0,00 ₽), пополните баланс: https://hub.neuraldeep.ru/app/billing» | пополнить кошелёк |
| 403 | модель не входит в тариф (`X-Window: free-model`), аккаунт заблокирован | сменить модель, тариф или режим ключа |
| 404 | нет такой модели, задачи или результата | проверить имя и id |
| 413 | файл или текст больше предела ручки | порезать вход |
| 415, 422 | формат не поддержан или параметр вне допустимых значений | исправить параметр |
| 429 | лимит частоты, параллельности или квоты, дневная ёмкость ключа, бесплатная квота транскрибации, пауза за повторы | подождать `Retry-After` секунд |
| 502, 503 | модель или сервис временно недоступны, модель перегружена у поставщика | повторить с паузой или выбрать другую модель |
| 504 (у транскрибации бывает 408) | модель не ответила за отведённое время | повторить, уменьшить вход |

Ошибки внешних поставщиков мы наружу не пробрасываем. Если поставщик отказал по своим причинам (авторизация, баланс, его лимиты), вы получите нейтральный `503`, а подробности уйдут нам в мониторинг. Как есть проходят только ошибки про сам ваш запрос: 400, 404, 413, 415, 422.

**Как узнать свою квоту.** Объёмы тарифов в документации не публикуем: они меняются, а ключ всегда может спросить свой остаток сам. Опрос этих ручек квоту не тратит.

| что | ручка |
|---|---|
| чат и эмбеддинги: окна, RPM, параллельность, кошелёк | `GET /v1/limits` ([подробно](https://neuraldeep.ru/docs/limits-api.md)) |
| поиск и краулинг | `GET /v1/search/quota` |
| OCR | `GET /v1/ocr/quota` |
| картинки | `GET /v1/images/quota` |
| музыка | `GET /v1/music/quota` |
| диаризация | `GET /v1/audio/diarize/quota` |
| озвучка | заголовки `X-Quota-Day-Remaining` и `X-Quota-Month-Remaining` в ответе `/v1/audio/speech` |

Успешный ответ гейта несёт заголовки `x-ratelimit-api_key-remaining-requests` (сколько запросов осталось в текущей минуте) и `x-ratelimit-api_key-remaining-max_parallel_requests` (сколько свободных потоков).

**429 от гейта моделей.** В ответе есть `Retry-After` (секунды), `Retry-After-Ms`, `X-Window` (какое окно сработало) и `X-RateLimit-Reset-Requests`. Текст ошибки заканчивается строкой `Limit resets at: ГГГГ-ММ-ДД ЧЧ:ММ:СС UTC`. Повторяйте после `Retry-After`, не раньше.

| `X-Window` | что случилось |
|---|---|
| `session` | исчерпан лимит запросов тарифа на 3 часа (окна фиксированные по UTC), идёт пауза |
| `week` | исчерпан недельный лимит, сброс в понедельник 00:00 UTC |
| `chat_rpm`, `model_rpm`, `account-rpm` | слишком много запросов в минуту: на аккаунт или к одной модели |
| `account-inflight`, `vector-inflight` | слишком много запросов в работе одновременно |
| `key-rpm`, `key-tpm`, `key-parallel` | сработал лимит самого ключа: запросы или токены в минуту, одновременные запросы |
| `daily-capacity` | исчерпана дневная ёмкость ключа, сброс в 00:00 UTC |
| `stt-free-daily` | кончилась бесплатная квота транскрибации на сегодня, сброс в 00:00 UTC |
| `abuse` | клиент много раз подряд повторял запрос после отказа, запросы аккаунта на паузе |

Подробнее и с примерами тел в разделе [лимиты и коды ошибок](https://neuraldeep.ru/docs/limits.md).

**429 от сервиса, когда кончилась квота.** Поиск, OCR, картинки, музыка, озвучка, PII-щит, диаризация и решения отвечают одинаково:

```json
{"error": {"type": "quota_exceeded", "pool": "search", "scope": "day",
           "used": 100, "limit": 100, "tier": "starter",
           "reset_at": "2026-10-23T00:00:00+00:00",
           "upgrade_url": "https://neuraldeep.ru/pricing",
           "message": "Лимит поиска исчерпан: 100/100 запросов за сутки, сброс в 00:00 UTC. Больше объёма: тариф выше (https://neuraldeep.ru/pricing) или оплата с кошелька (https://hub.neuraldeep.ru/app/billing)."}}
```

Числа в примере условные. Поле `message` написано для человека, программе лучше читать остальные поля. Если услуга в тариф не входит вовсе (`limit: 0`), текст начинается с «Ваш тариф не включает…». Заголовки: `X-Quota-Pool`, `X-Quota-Scope` (`day` или `month`), `X-Quota-Limit`, `X-Quota-Reset` и `Retry-After` до сброса. Дневные квоты сбрасываются в 00:00 UTC, месячные первого числа месяца в 00:00 UTC.

У ключа в режиме «Кошелёк» без денег сервисы отвечают `402` с текстом «Кошелёк пуст (0,00 ₽), пополните баланс: https://hub.neuraldeep.ru/app/billing». Слишком много своих задач в очереди картинок дают `429` с текстом «У вас уже 5 задач в очереди из 5. Дождитесь, пока они завершатся.» и `Retry-After`.