Переход с v2 и v3 на v1
API /v1 сохраняет все продукты, но меняет пути, заголовок с ключом, тела ответов и ошибок и некоторые имена полей. Здесь перечислены все изменения.
Что меняется
- Все продукты переезжают на один базовый URL:
https://my.neuronai.uz/api/v1. - Ключ передаётся в
Authorization: Bearer, а не вX-Api-Key. successбольше нет: JSON-ответ содержитdataиrequest_id, а у всех ошибок одна форма с постоянным кодом.- Все имена полей записаны в snake_case, а метки времени заканчиваются на
Z. - Ключи показываются только один раз и могут быть ограничены выбранными продуктами. Уже существующие ключи имеют полный доступ, поэтому продолжают работать.
- Старые пути удалены и отвечают 404. Переведите код на пути ниже.
Пути
Большинство путей меняют только версию. Примечания добавляют, что ещё изменилось в пути.
| Было | Стало |
|---|---|
POST /api/v3/tts/synthesize | POST /api/v1/tts/synthesize |
POST /api/v3/tts/dialogue | POST /api/v1/tts/dialogueТеперь принимает |
POST /api/v3/tts/jobs | POST /api/v1/tts/jobs |
GET /api/v3/tts/jobs/{id} | GET /api/v1/tts/jobs/{id} |
GET /api/v3/tts/jobs/{id}/audio | GET /api/v1/tts/jobs/{id}/audio |
GET /api/v3/tts/voices | GET /api/v1/tts/voices?type=stockСписок приходит постранично: переходите по |
GET /api/v3/tts/my-voices | GET /api/v1/tts/voices?type=customНужно право |
POST /api/v3/tts/voices | POST /api/v1/tts/voicesТеперь принимает |
PUT /api/v3/tts/voices/{id} | PATCH /api/v1/tts/voices/{id}Только JSON. Передавайте только изменяемые поля. |
POST /api/v3/tts/voices/{id} (_method=PUT) | POST /api/v1/tts/voices/{id}/audioЗаменяет эталонное аудио, поле |
DELETE /api/v3/tts/voices/{id} | DELETE /api/v1/tts/voices/{id}Отвечает 204 без тела. |
POST /api/v2/stt/transcribe | POST /api/v1/stt/transcribe |
GET /api/v2/user/balance | GET /api/v1/balanceНовое тело: смотрите ниже. |
GET /api/v1/balance | GET /api/v1/balanceНовое тело: смотрите ниже. |
GET /api/v1/usage | GET /api/v1/usageНовое тело: смотрите ниже. |
POST /api/v2/tts/synthesize | POST /api/v1/tts/synthesizeMP3-движок выведен из работы: /v1 синтезирует WAV своими голосами. Выберите |
GET /api/v2/tts/voices | GET /api/v1/tts/voicesMP3-движок выведен из работы: /v1 синтезирует WAV своими голосами. Выберите |
Эндпоинты, совместимые с OpenAI и Cohere, сохраняют пути и тела успешных ответов: /api/v1/chat/completions, /api/v1/models, /api/v1/embeddings, а также /api/v1/rerank и его двойник для Cohere /api/v2/rerank. Меняются только их ошибки, как описано ниже.
Аутентификация
Передавайте ключ как Authorization: Bearer nai_… в каждом запросе; X-Api-Key больше не документирован. Ключ, отправленный в список голосов, теперь проверяется, поэтому неверный ключ получает ответ 401, а не общедоступный список.
Тела ответов
success убран, потому что об успехе говорит статус. На перенесённых эндпоинтах объект приходит в data, список — в data вместе с next_cursor, и в каждом таком теле есть request_id. Создание отвечает 201, поставленная в очередь задача — 202 с Location, удаление — 204 без тела.
Список голосов приходит страницами по 50 по умолчанию, до 100 с параметром limit. Передавайте последний next_cursor как cursor, чтобы получить следующую страницу, пока next_cursor не станет null.
Ошибки
Теперь у каждой ошибки одно тело: error с полями type, code, message и param, а затем request_id. Ошибка валидации добавляет fields с первым сообщением для каждого поля, тогда как раньше errors перечислял все сообщения. Принимайте решения по error.code, а не по тексту сообщения.
Сообщение voice_id is not available for your account сохраняет формулировку, но проверяйте вместо него код voice_unavailable.
Повторное использование Idempotency-Key с другим телом теперь получает ответ 409 idempotency_conflict. Старые пути молча возвращали первый ответ.
На эндпоинтах, совместимых с OpenAI, объект ошибки получает param и request_id, а отклонённый ключ сообщает причину в code, например api_key_revoked, там, где раньше был invalid_api_key.
Переименованные поля
Все поля записаны в snake_case. Вот поля, которые изменились.
Задача синтеза
| Было | Стало |
|---|---|
createdAt | created_at |
startedAt | started_at |
finishedAt | finished_at |
characterCount | character_count |
balanceAfter | balance_after |
voiceCustom | voice_custom |
latencyMs | latency_ms |
referralReward | referral_rewardУдалено в /v1. Пригласившему сообщают напрямую. |
audioUrl | audio_urlВедёт на аудио-эндпоинт /v1. |
Голос
| Было | Стало |
|---|---|
refText | ref_text |
createdAt | created_at |
tags | tagsВсегда список, никогда не |
typeНовое поле: |
Распознавание
| Было | Стало |
|---|---|
durationSeconds | duration_seconds |
requestId | request_idВынесен из |
referralReward | referral_rewardУдалено в /v1. Пригласившему сообщают напрямую. |
Баланс
| Было | Стало |
|---|---|
sttPricePerSecond | stt_price_per_second |
ttsPricePerChar | tts_price_per_char |
minTopup | min_topup |
Расходы
| Было | Стало |
|---|---|
by_key[].api_key_id | by_key[].idПубличный идентификатор ключа или |
period.start | period.startТеперь охватывает |
Метки времени записываются в RFC 3339 по UTC и заканчиваются на Z, а раньше заканчивались на +00:00.
Заголовки
| Заголовок | Что изменилось |
|---|---|
X-Request-Id | Есть в каждом ответе. Всегда указывает текущий запрос, в том числе при повторе. |
X-Referral-Reward | Удалено в /v1. Пригласившему сообщают напрямую. |
X-Audio-Url | Больше не отправляется. |
X-Character-CountX-BalanceX-Voice-Custom | Теперь отправляются и в ответах диалога. |
X-Turns | Те же ключи, а смещения всегда дробные числа. |
Idempotency-Replayed | Теперь отправляется и при повторе распознавания или создания голоса. |
API ключи
Теперь ключи хранятся только в виде хеша, поэтому ключ показывается один раз, при создании, и больше никогда. Если ключ потерян, создайте новый, переключите на него приложения и отзовите старый.
Все ключи, созданные до появления прав, имеют полный доступ, поэтому ничего не перестанет работать. Новым ключам выдавайте только нужные продукты.