Перейти к содержанию

Переход с 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/synthesizePOST /api/v1/tts/synthesize
POST /api/v3/tts/dialoguePOST /api/v1/tts/dialogue

Теперь принимает Idempotency-Key.

POST /api/v3/tts/jobsPOST /api/v1/tts/jobs
GET /api/v3/tts/jobs/{id}GET /api/v1/tts/jobs/{id}
GET /api/v3/tts/jobs/{id}/audioGET /api/v1/tts/jobs/{id}/audio
GET /api/v3/tts/voicesGET /api/v1/tts/voices?type=stock

Список приходит постранично: переходите по next_cursor.

GET /api/v3/tts/my-voicesGET /api/v1/tts/voices?type=custom

Нужно право voices:read. Без него список пуст.

POST /api/v3/tts/voicesPOST /api/v1/tts/voices

Теперь принимает Idempotency-Key.

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

Заменяет эталонное аудио, поле _method не нужно.

DELETE /api/v3/tts/voices/{id}DELETE /api/v1/tts/voices/{id}

Отвечает 204 без тела.

POST /api/v2/stt/transcribePOST /api/v1/stt/transcribe
GET /api/v2/user/balanceGET /api/v1/balance

Новое тело: смотрите ниже.

GET /api/v1/balanceGET /api/v1/balance

Новое тело: смотрите ниже.

GET /api/v1/usageGET /api/v1/usage

Новое тело: смотрите ниже.

POST /api/v2/tts/synthesizePOST /api/v1/tts/synthesize

MP3-движок выведен из работы: /v1 синтезирует WAV своими голосами. Выберите voice_id из списка /v1.

GET /api/v2/tts/voicesGET /api/v1/tts/voices

MP3-движок выведен из работы: /v1 синтезирует WAV своими голосами. Выберите voice_id из списка /v1.

Эндпоинты, совместимые с 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 без тела.

Было
{
  "success": true,
  "data": {
    "id": "01j9x3c5d6e7f8g9h0j1k2m3n4",
    "status": "succeeded",
    "createdAt": "2026-09-25T10:00:00+00:00",
    "characterCount": 42,
    "audioUrl": "https://my.neuronai.uz/api/v3/tts/jobs/01j9x3c5d6e7f8g9h0j1k2m3n4/audio"
  }
}

Стало
{
  "data": {
    "id": "01j9x3c5d6e7f8g9h0j1k2m3n4",
    "status": "succeeded",
    "created_at": "2026-09-25T10:00:00Z",
    "character_count": 42,
    "audio_url": "https://my.neuronai.uz/api/v1/tts/jobs/01j9x3c5d6e7f8g9h0j1k2m3n4/audio"
  },
  "request_id": "0b8e8a5e-6f5c-4f7e-9d63-2c1f0f4b7a51"
}

Список голосов приходит страницами по 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. Вот поля, которые изменились.

Задача синтеза

БылоСтало
createdAtcreated_at
startedAtstarted_at
finishedAtfinished_at
characterCountcharacter_count
balanceAfterbalance_after
voiceCustomvoice_custom
latencyMslatency_ms
referralRewardreferral_reward

Удалено в /v1. Пригласившему сообщают напрямую.

audioUrlaudio_url

Ведёт на аудио-эндпоинт /v1.

Голос

БылоСтало
refTextref_text
createdAtcreated_at
tagstags

Всегда список, никогда не null.

type

Новое поле: stock или custom.

Распознавание

БылоСтало
durationSecondsduration_seconds
requestIdrequest_id

Вынесен из data на уровень выше.

referralRewardreferral_reward

Удалено в /v1. Пригласившему сообщают напрямую.

Баланс

БылоСтало
sttPricePerSecondstt_price_per_second
ttsPricePerChartts_price_per_char
minTopupmin_topup

Расходы

БылоСтало
by_key[].api_key_idby_key[].id

Публичный идентификатор ключа или null для запросов из панели управления.

period.startperiod.start

Теперь охватывает days целых дней, включая сегодня.

Метки времени записываются в 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 ключи

Теперь ключи хранятся только в виде хеша, поэтому ключ показывается один раз, при создании, и больше никогда. Если ключ потерян, создайте новый, переключите на него приложения и отзовите старый.

Все ключи, созданные до появления прав, имеют полный доступ, поэтому ничего не перестанет работать. Новым ключам выдавайте только нужные продукты.