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: Bearerinstead ofX-Api-Key. successis gone: a JSON answer holdsdataandrequest_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.
| Before | Now |
|---|---|
POST /api/v3/tts/synthesize | POST /api/v1/tts/synthesize |
POST /api/v3/tts/dialogue | POST /api/v1/tts/dialogueNow takes an |
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=stockThe list comes in pages: follow |
GET /api/v3/tts/my-voices | GET /api/v1/tts/voices?type=customNeeds |
POST /api/v3/tts/voices | POST /api/v1/tts/voicesNow takes an |
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}/audioReplaces the reference audio, with no |
DELETE /api/v3/tts/voices/{id} | DELETE /api/v1/tts/voices/{id}Answers 204 with no body. |
POST /api/v2/stt/transcribe | POST /api/v1/stt/transcribe |
GET /api/v2/user/balance | GET /api/v1/balanceNew body: see below. |
GET /api/v1/balance | GET /api/v1/balanceNew body: see below. |
GET /api/v1/usage | GET /api/v1/usageNew body: see below. |
POST /api/v2/tts/synthesize | POST /api/v1/tts/synthesizeThe MP3 engine is retired: /v1 synthesizes WAV, with voices of its own. Pick a |
GET /api/v2/tts/voices | GET /api/v1/tts/voicesThe MP3 engine is retired: /v1 synthesizes WAV, with voices of its own. Pick a |
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.
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
| Before | Now |
|---|---|
createdAt | created_at |
startedAt | started_at |
finishedAt | finished_at |
characterCount | character_count |
balanceAfter | balance_after |
voiceCustom | voice_custom |
latencyMs | latency_ms |
referralReward | referral_rewardRemoved in /v1. The referrer is notified directly. |
audioUrl | audio_urlPoints at the /v1 audio endpoint. |
Voice
| Before | Now |
|---|---|
refText | ref_text |
createdAt | created_at |
tags | tagsAlways a list, never |
typeNew: |
Transcription
| Before | Now |
|---|---|
durationSeconds | duration_seconds |
requestId | request_idMoved out of |
referralReward | referral_rewardRemoved in /v1. The referrer is notified directly. |
Balance
| Before | Now |
|---|---|
sttPricePerSecond | stt_price_per_second |
ttsPricePerChar | tts_price_per_char |
minTopup | min_topup |
Usage
| Before | Now |
|---|---|
by_key[].api_key_id | by_key[].idThe key's public id, or |
period.start | period.startNow counts |
Timestamps are RFC 3339 in UTC and end in Z, where they used to end in +00:00.
Headers
| Header | What 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.