Открыть в интерактивной справке · markdown для агентов: https://neuraldeep.ru/docs/start.md

Начало работы

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

что значение
базовый адрес https://api.neuraldeep.ru/v1
авторизация заголовок Authorization: Bearer sk-...
ключ кабинет, раздел «Ключи»
каталог моделей ключа GET /v1/models
витрина моделей и цены /models 
curl -s https://api.neuraldeep.ru/v1/models \
  -H "Authorization: Bearer $YOUR_KEY" | jq '.data[].id'

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

Формат ошибок. Гейт моделей (чат, эмбеддинги, реранк, транскрибация) отвечает как 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 (подробно)
поиск и краулинг 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 клиент много раз подряд повторял запрос после отказа, запросы аккаунта на паузе

Подробнее и с примерами тел в разделе лимиты и коды ошибок.

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

{"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.

Разделы справки (markdown для агентов)