Skip to content

Move from v2 and v3 to v1

The /v1 API keeps every product and changes the paths, the header that carries your key, the answer and error bodies and some field names. This page lists every change.

What changes

  • Every product moves under one base URL, https://my.neuronai.uz/api/v1.
  • Your key goes in Authorization: Bearer instead of X-Api-Key.
  • success is gone: a JSON answer holds data and request_id, and every error has one shape with a stable code.
  • Every field name is snake_case, and timestamps end in Z.
  • Keys are shown only once and can be limited to chosen products. Keys you already have hold full access, so they keep working.
  • The old paths have been removed and answer 404. Move your code to the paths below.

Paths

Most paths change only their version. The notes add what else is different about a path.

BeforeNow
POST /api/v3/tts/synthesizePOST /api/v1/tts/synthesize
POST /api/v3/tts/dialoguePOST /api/v1/tts/dialogue

Now takes an 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

The list comes in pages: follow next_cursor.

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

Needs voices:read. Without it, the list is empty.

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

Now takes an Idempotency-Key.

PUT /api/v3/tts/voices/{id}PATCH /api/v1/tts/voices/{id}

JSON only. Send just the fields to change.

POST /api/v3/tts/voices/{id} (_method=PUT)POST /api/v1/tts/voices/{id}/audio

Replaces the reference audio, with no _method field.

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

Answers 204 with no body.

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

New body: see below.

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

New body: see below.

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

New body: see below.

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

The MP3 engine is retired: /v1 synthesizes WAV, with voices of its own. Pick a voice_id from the /v1 list.

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

The MP3 engine is retired: /v1 synthesizes WAV, with voices of its own. Pick a voice_id from the /v1 list.

The OpenAI- and Cohere-compatible endpoints keep their paths and their success bodies: /api/v1/chat/completions, /api/v1/models, /api/v1/embeddings, and /api/v1/rerank with its Cohere twin /api/v2/rerank. Only their errors change, as below.

Authentication

Send the key as Authorization: Bearer nai_… on every request; X-Api-Key is no longer documented. A key sent to the voice list is now checked, so a bad one answers 401 instead of the public list.

Answer bodies

success is gone, because the status says it. On the endpoints that moved, an object comes under data, a list under data with next_cursor, and every one of these bodies has request_id. A create answers 201, a queued job 202 with Location, and a delete 204 with no body.

Before
{
  "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"
  }
}

Now
{
  "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"
}

The voice list comes in pages of 50 by default, up to 100 with limit. Pass the last next_cursor as cursor for the next page, until next_cursor is null.

Errors

Every error has one body now: error with type, code, message and param, then request_id. A validation error adds fields, which gives each field its first message, where errors used to list them all. Decide by error.code rather than by the message.

The message voice_id is not available for your account keeps its words, but match the code voice_unavailable instead.

Reusing an Idempotency-Key with a different body now answers 409 idempotency_conflict. The old paths replayed the first answer without a word.

On the OpenAI-compatible endpoints the error object gains param and request_id, and a refused key says why in code, such as api_key_revoked, where it used to say invalid_api_key.

Renamed fields

Every field is snake_case. These are the fields that changed.

Synthesis job

BeforeNow
createdAtcreated_at
startedAtstarted_at
finishedAtfinished_at
characterCountcharacter_count
balanceAfterbalance_after
voiceCustomvoice_custom
latencyMslatency_ms
referralRewardreferral_reward

Removed in /v1. The referrer is notified directly.

audioUrlaudio_url

Points at the /v1 audio endpoint.

Voice

BeforeNow
refTextref_text
createdAtcreated_at
tagstags

Always a list, never null.

type

New: stock or custom.

Transcription

BeforeNow
durationSecondsduration_seconds
requestIdrequest_id

Moved out of data, next to it.

referralRewardreferral_reward

Removed in /v1. The referrer is notified directly.

Balance

BeforeNow
sttPricePerSecondstt_price_per_second
ttsPricePerChartts_price_per_char
minTopupmin_topup

Usage

BeforeNow
by_key[].api_key_idby_key[].id

The key's public id, or null for requests from the dashboard.

period.startperiod.start

Now counts days whole days, today included.

Timestamps are RFC 3339 in UTC and end in Z, where they used to end in +00:00.

Headers

HeaderWhat changed
X-Request-Id
On every answer. It always names the current request, a replay included.
X-Referral-Reward
Removed in /v1. The referrer is notified directly.
X-Audio-Url
No longer sent.
X-Character-CountX-BalanceX-Voice-Custom
Now sent on dialogue answers too.
X-Turns
Same keys, and the offsets are always decimal numbers.
Idempotency-Replayed
Now also sent when a transcription or a voice creation is replayed.

API keys

Keys are stored only as a hash now, so a key is shown once, when it is created, and never again. If you have lost one, create a new key, switch your applications to it and revoke the old one.

Every key made before key permissions is a full-access key, so nothing stops working. Give new keys only the products they need.