{"openapi":"3.1.0","info":{"title":"NeuronAI API","version":"1.0.0","description":"NeuronAI developer API: text-to-speech and voice cloning, speech-to-text, language models, embeddings, reranking, your account and API keys. Every route lives under /v1."},"servers":[{"url":"https://my.neuronai.uz/api","description":"Production"}],"security":[{"bearer":[]}],"tags":[{"name":"LLM","description":"OpenAI-compatible chat completions. Point any OpenAI SDK at this base URL and authenticate with your API key."},{"name":"TTS","description":"Text-to-Speech synthesis, dialogue, async jobs and the voice catalog."},{"name":"Voice cloning","description":"Create and manage voice clones for use with TTS synthesis."},{"name":"STT","description":"Speech-to-Text transcription."},{"name":"Embeddings","description":"Vector embeddings for semantic search and RAG. OpenAI-compatible — point your OpenAI SDK at this base URL."},{"name":"Rerank","description":"Cross-encoder reranking for retrieval pipelines. Cohere-compatible — available at both /v1/rerank and /v2/rerank."},{"name":"Account","description":"Read your own spend, request counts and remaining balance. Free — these endpoints are never billed."},{"name":"API keys","description":"Create, list, change and revoke your organization's API keys from code. Every call needs a key holding the `api_keys` permission: `read` to list and get, `write` to create, change and revoke. These endpoints allow 60 requests a minute per user."}],"paths":{"/v1/chat/completions":{"post":{"operationId":"createChatCompletion","description":"Generates a model response for a chat conversation. OpenAI-compatible — set your OpenAI SDK's base URL to `{app}/api/v1` and use your API key. Set `stream: true` for a Server-Sent Events stream of `chat.completion.chunk` objects ending with `[DONE]` (the chunk before it carries `usage` when the model reports its token counts). Billed per token (prompt + completion).","summary":"Create chat completion","tags":["LLM"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatCompletionRequest"}}}},"responses":{"200":{"description":"The completion: one choice holding the assistant's message, and `usage` counting the tokens billed. With `stream: true`, the completion comes as Server-Sent Events instead (`text/event-stream`).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","const":"assistant"},"content":{"type":"string"}},"required":["role","content"]},"finish_reason":{"type":"string"}},"required":["index","message","finish_reason"]}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","completion_tokens","total_tokens"]}},"required":["id","object","created","model","choices","usage"]}},"text/event-stream":{"schema":{"type":"string","description":"Sent instead of the JSON when `stream: true`. Each event is a `data: ` line holding one JSON object, then a blank line:\n\n1. A `chat.completion.chunk` whose `choices[0].delta` is `{\"role\": \"assistant\"}`.\n2. One chunk for each piece of the answer, with the text in `choices[0].delta.content`. `finish_reason` is `null` until the chunk that ends the answer, which names it; that chunk may have an empty `delta`.\n3. When the model reports its token counts, one more chunk with `choices: []` and `usage` (`prompt_tokens`, `completion_tokens`, `total_tokens`).\n4. Last, always: `data: [DONE]`, which is not JSON.\n\nEvery chunk repeats the same `id`, `created` and `model`. If the model fails once the stream has started, the status stays 200: one event holding the error envelope, with the code `upstream_error`, takes the place of the chunks still to come and of the `usage` chunk, and `data: [DONE]` follows. The prompt and the text already sent are billed, from estimated token counts."}}},"headers":{"X-Cost":{"description":"The price billed, in credits. Sent with the JSON completion; a stream is billed when it ends, so it carries none.","schema":{"type":"number"}},"X-Accel-Buffering":{"description":"Sent as `no` with a stream: it tells a proxy such as nginx not to hold back the events.","schema":{"type":"string","const":"no"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance for the most this request can cost (`insufficient_balance`), or that cost would pass this key's monthly spend limit (`spend_limit_exceeded`). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"404":{"description":"`model` is not one of the models `GET /api/v1/models` lists: `model_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation (`invalid_request`: `error.param` names the first invalid field and `error.fields` maps each one to its message), or the prompt, with room for `max_tokens` (the server's cap when it is left out), does not fit the model's context window (`context_length_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"502":{"description":"Without `stream`: the model failed or could not be reached, `upstream_error`. Nothing is charged. A stream reports a failure as an event instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"1K tokens","rates":[{"label":"Input","value":1.5,"currency":"credits"},{"label":"Output","value":6,"currency":"credits"}]},"security":[{"bearer":["llm:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/chat/completions\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"model\": \"gemma-4-26b-a4b\",\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"Salom! Bugun ob-havo qanday?\"}\n    ]\n  }'"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst completion = await client.chat.completions.create({\n    model: \"gemma-4-26b-a4b\",\n    messages: [{role: \"user\", content: \"Salom! Bugun ob-havo qanday?\"}],\n});\n\nconsole.log(completion.choices[0]?.message.content);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\ncompletion = client.chat.completions.create(\n    model=\"gemma-4-26b-a4b\",\n    messages=[{\"role\": \"user\", \"content\": \"Salom! Bugun ob-havo qanday?\"}],\n)\n\nprint(completion.choices[0].message.content)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$completion = $client->chat->completions->create([\n    'model' => 'gemma-4-26b-a4b',\n    'messages' => [\n        ['role' => 'user', 'content' => 'Salom! Bugun ob-havo qanday?'],\n    ],\n]);\n\necho $completion->choices[0]->message->content, PHP_EOL;"},{"lang":"python","label":"Python (OpenAI SDK)","source":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://my.neuronai.uz/api/v1\", api_key=\"<your-api-key>\")\n\ncompletion = client.chat.completions.create(\n    model=\"gemma-4-26b-a4b\",\n    messages=[{\"role\": \"user\", \"content\": \"Salom! Bugun ob-havo qanday?\"}],\n)\n\nprint(completion.choices[0].message.content)"},{"lang":"javascript","label":"JavaScript (OpenAI SDK)","source":"import OpenAI from 'openai';\n\nconst client = new OpenAI({\n    baseURL: 'https://my.neuronai.uz/api/v1',\n    apiKey: '<your-api-key>',\n});\n\nconst completion = await client.chat.completions.create({\n    model: 'gemma-4-26b-a4b',\n    messages: [{ role: 'user', content: 'Salom! Bugun ob-havo qanday?' }],\n});\n\nconsole.log(completion.choices[0].message.content);"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/chat/completions');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'Authorization: Bearer <your-api-key>',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'model' => 'gemma-4-26b-a4b',\n        'messages' => [\n            ['role' => 'user', 'content' => 'Salom! Bugun ob-havo qanday?'],\n        ],\n    ]),\n]);\n\n$response = json_decode(curl_exec($ch), true);\ncurl_close($ch);\n\necho $response['choices'][0]['message']['content'];"}]}},"/v1/models":{"get":{"operationId":"listModels","description":"Lists the chat models available to your account.","summary":"List models","tags":["LLM"],"responses":{"200":{"description":"The chat models, in OpenAI's list shape. Send a model's `id` as `model`. `created` is always `0`.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"model"},"created":{"type":"integer"},"owned_by":{"type":"string"}},"required":["id","object","created","owned_by"]}}},"required":["object","data"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["llm:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst models = await client.models.list();\n\nfor (const model of models.data) {\n    console.log(model.id);\n}"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nmodels = client.models.list()\n\nfor model in models.data:\n    print(model.id)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$models = $client->models->list();\n\nforeach ($models->data as $model) {\n    echo $model->id, PHP_EOL;\n}"}]}},"/v1/tts/synthesize":{"post":{"operationId":"synthesizeSpeech","description":"Synthesizes speech from text and answers with WAV audio. Pass `voice_id` to use a stock voice or one of your voice clones.\n\nOptional `quality` selects a latency/fidelity preset: `fast` (lowest latency, slightly reduced detail), `standard` (default, balanced), `high` (best fidelity, slowest).\n\nPass an `Idempotency-Key` header to make retries safe: replaying the same key returns the original audio and headers instead of synthesizing and charging again. Keys are scoped to your organization, must not exceed 191 characters (a longer key answers 400 `invalid_request` before anything is synthesized or charged), and are remembered for 7 days. The same key sent with a different body answers 409 `idempotency_conflict`.\n\nThe response carries the price billed (`X-Cost`), billed character count (`X-Character-Count`), your balance after the charge (`X-Balance`), voice type (`X-Voice-Custom`), upstream latency (`X-Latency-Ms`) and a request id (`X-Request-Id`) in headers. A response replayed from an `Idempotency-Key` also carries `Idempotency-Replayed: 1`.\n\nEmotion tags are bracketed directions the voice acts out rather than reads aloud: `[laughter]`, `[sigh]`, `[dissatisfaction-hnn]`, `[confirmation-en]`, `[question-en]`, `[question-ah]`, `[question-oh]`, `[question-ei]`, `[question-yi]`, `[surprise-ah]`, `[surprise-oh]`, `[surprise-wa]`, `[surprise-yo]`. Write them inline in the text. Each bills as one character rather than as its spelling, so a tag costs the same however long its name is.","summary":"Synthesize speech","tags":["TTS"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Makes a retry safe: the same key again returns the original audio and headers instead of synthesizing and charging again. At most 191 characters, scoped to your organization and kept for 7 days.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeSpeechRequest"}}}},"responses":{"200":{"description":"WAV audio of the synthesized speech. Pricing, latency and the request id are in headers.","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Cost":{"description":"The price billed, in credits.","schema":{"type":"number"}},"X-Balance":{"description":"Your balance after the charge, in credits.","schema":{"type":"number"}},"X-Character-Count":{"description":"The characters billed. An emotion tag counts as one.","schema":{"type":"integer"}},"X-Voice-Custom":{"description":"`1` when the voice is one of your clones, `0` for a stock voice.","schema":{"type":"string","enum":["0","1"]}},"X-Latency-Ms":{"description":"Time the voice took, in milliseconds. May have a fraction.","schema":{"type":"number"}},"Idempotency-Replayed":{"description":"`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"400":{"description":"The `Idempotency-Key` is over 191 characters: `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"409":{"description":"The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"500":{"description":"Synthesis failed: `synthesis_failed`; nothing is charged. A replay whose recorded audio can no longer be read answers `server_error`. Anything else that fails unexpectedly: `server_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"503":{"description":"Either the audio was made but could not be stored for an idempotent retry (`storage_failed`), or the API itself is down for maintenance (`service_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"char","rates":[{"label":"Default voice","value":0.3,"currency":"credits"},{"label":"Voice clone","value":0.5,"currency":"credits"}]},"security":[{"bearer":["tts:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/tts/synthesize\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"voice_id\": \"kamron\",\n    \"text\": \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n    \"language\": \"uz\",\n    \"quality\": \"standard\"\n  }' \\\n  --output speech.wav"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst speech = await client.tts.synthesize({\n    voice_id: \"kamron\",\n    text: \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n    language: \"uz\",\n    quality: \"standard\",\n});\n\nawait speech.save(\"speech.wav\");"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nspeech = client.tts.synthesize(\n    voice_id=\"kamron\",\n    text=\"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n    language=\"uz\",\n    quality=\"standard\",\n)\n\nspeech.save(\"speech.wav\")"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$speech = $client->tts->synthesize([\n    'voice_id' => 'kamron',\n    'text' => 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.',\n    'language' => 'uz',\n    'quality' => 'standard',\n]);\n\n$speech->save('speech.wav');"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/tts/synthesize', {\n    method: 'POST',\n    headers: {\n        'Authorization': 'Bearer <your-api-key>',\n        'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n        voice_id: 'kamron',\n        text: 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.',\n        language: 'uz',\n        quality: 'standard',\n    }),\n});\n\nif (!response.ok) {\n    throw new Error(`Request failed: ${response.status}`);\n}\n\nconst audioBlob = await response.blob();\nconst audio = new Audio(URL.createObjectURL(audioBlob));\nawait audio.play();"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    \"https://my.neuronai.uz/api/v1/tts/synthesize\",\n    headers={\"Authorization\": \"Bearer <your-api-key>\"},\n    json={\n        \"voice_id\": \"kamron\",\n        \"text\": \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n        \"language\": \"uz\",\n        \"quality\": \"standard\",\n    },\n)\n\nresponse.raise_for_status()\n\nwith open(\"speech.wav\", \"wb\") as f:\n    f.write(response.content)"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/tts/synthesize');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'Authorization: Bearer <your-api-key>',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'voice_id' => 'kamron',\n        'text' => 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.',\n        'language' => 'uz',\n        'quality' => 'standard',\n    ]),\n]);\n\n$audio = curl_exec($ch);\ncurl_close($ch);\n\nfile_put_contents('speech.wav', $audio);"}]}},"/v1/tts/dialogue":{"post":{"operationId":"synthesizeDialogue","description":"Renders a multi-speaker script into one stitched WAV file. `turns` holds 1–100 entries, each with a `voice_id` (a stock voice or one of your clones) and its `text`, and optionally its own `language`, `quality` and `speed`; `gap_ms` (0–5000) sets the silence between turns. Billed per character, per turn, at that turn's own rate.\n\nOver 10000 characters in total answers 413 `input_too_large`; a single turn over its own limit answers 422 `invalid_request`.\n\nThe response carries `X-Cost`, `X-Balance`, `X-Character-Count`, `X-Voice-Custom`, `X-Latency-Ms` and `X-Request-Id`, as synthesize does. It adds per-turn start and end offsets in `X-Turns` (a JSON array with snake_case keys) and the number of turns in `X-Turn-Count`, so a client can seek to a line. `Idempotency-Key` works as on synthesize.\n\nEmotion tags are bracketed directions the voice acts out rather than reads aloud: `[laughter]`, `[sigh]`, `[dissatisfaction-hnn]`, `[confirmation-en]`, `[question-en]`, `[question-ah]`, `[question-oh]`, `[question-ei]`, `[question-yi]`, `[surprise-ah]`, `[surprise-oh]`, `[surprise-wa]`, `[surprise-yo]`. Write them inline in the text. Each bills as one character rather than as its spelling, so a tag costs the same however long its name is.","summary":"Synthesize a dialogue","tags":["TTS"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Makes a retry safe: the same key again returns the original audio and headers instead of synthesizing and charging again. At most 191 characters, scoped to your organization and kept for 7 days.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeDialogueRequest"}}}},"responses":{"200":{"description":"WAV audio of the stitched dialogue. Per-turn offsets are in `X-Turns`; pricing, latency and the request id are in headers.","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Cost":{"description":"The price billed, in credits.","schema":{"type":"number"}},"X-Balance":{"description":"Your balance after the charge, in credits.","schema":{"type":"number"}},"X-Character-Count":{"description":"The characters billed. An emotion tag counts as one.","schema":{"type":"integer"}},"X-Voice-Custom":{"description":"`1` when any turn used one of your clones, else `0`.","schema":{"type":"string","enum":["0","1"]}},"X-Latency-Ms":{"description":"Time the voices took, in milliseconds. May have a fraction.","schema":{"type":"number"}},"Idempotency-Replayed":{"description":"`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string"}},"X-Turns":{"description":"Where each turn is in the audio, so a client can seek to a line: a JSON array with one object per turn, holding `index`, `voice_id`, `start_s`, `end_s` and `duration_s`. The times are in seconds.","schema":{"type":"string"}},"X-Turn-Count":{"description":"The number of turns rendered.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"400":{"description":"The `Idempotency-Key` is over 191 characters: `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"409":{"description":"The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"413":{"description":"Either the script is over 10000 characters in total, or the request body itself is larger than the server accepts — either way, `input_too_large`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"500":{"description":"Synthesis failed: `synthesis_failed`; nothing is charged. A replay whose recorded audio can no longer be read answers `server_error`. Anything else that fails unexpectedly: `server_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"503":{"description":"Either the audio was made but could not be stored for an idempotent retry (`storage_failed`), or the API itself is down for maintenance (`service_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"char","rates":[{"label":"Default voice","value":0.3,"currency":"credits"},{"label":"Voice clone","value":0.5,"currency":"credits"}]},"security":[{"bearer":["tts:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/tts/dialogue\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"turns\": [\n      {\"voice_id\": \"<voice-a>\", \"text\": \"Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.\"},\n      {\"voice_id\": \"<voice-b>\", \"text\": \"Xush kelibsiz! Birinchi yangilikni tinglaymiz.\"}\n    ],\n    \"gap_ms\": 300\n  }' \\\n  --output dialogue.wav"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst dialogue = await client.tts.dialogue({\n    turns: [\n        {voice_id: \"kamron\", text: \"Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.\"},\n        {voice_id: \"madina\", text: \"Xush kelibsiz! Birinchi yangilikni tinglaymiz.\"},\n    ],\n    gap_ms: 300,\n});\n\nawait dialogue.save(\"dialogue.wav\");\nconsole.log(dialogue.turns);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\ndialogue = client.tts.dialogue(\n    turns=[\n        {\"voice_id\": \"kamron\", \"text\": \"Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.\"},\n        {\"voice_id\": \"madina\", \"text\": \"Xush kelibsiz! Birinchi yangilikni tinglaymiz.\"},\n    ],\n    gap_ms=300,\n)\n\ndialogue.save(\"dialogue.wav\")\nprint(dialogue.turns)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$dialogue = $client->tts->dialogue([\n    'turns' => [\n        ['voice_id' => 'kamron', 'text' => 'Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.'],\n        ['voice_id' => 'madina', 'text' => 'Xush kelibsiz! Birinchi yangilikni tinglaymiz.'],\n    ],\n    'gap_ms' => 300,\n]);\n\n$dialogue->save('dialogue.wav');\nprint_r($dialogue->turns);"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/tts/dialogue', {\n    method: 'POST',\n    headers: {\n        'Authorization': 'Bearer <your-api-key>',\n        'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n        turns: [\n            { voice_id: '<voice-a>', text: 'Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.' },\n            { voice_id: '<voice-b>', text: 'Xush kelibsiz! Birinchi yangilikni tinglaymiz.' },\n        ],\n        gap_ms: 300,\n    }),\n});\n\nif (!response.ok) {\n    throw new Error(`Request failed: ${response.status}`);\n}\n\n// Per-turn start/end offsets, so a client can seek to a line.\nconst turns = JSON.parse(response.headers.get('X-Turns'));\n\nconst audioBlob = await response.blob();\nconst audio = new Audio(URL.createObjectURL(audioBlob));\nawait audio.play();"},{"lang":"python","label":"Python","source":"import json\n\nimport requests\n\nresponse = requests.post(\n    \"https://my.neuronai.uz/api/v1/tts/dialogue\",\n    headers={\"Authorization\": \"Bearer <your-api-key>\"},\n    json={\n        \"turns\": [\n            {\"voice_id\": \"<voice-a>\", \"text\": \"Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.\"},\n            {\"voice_id\": \"<voice-b>\", \"text\": \"Xush kelibsiz! Birinchi yangilikni tinglaymiz.\"},\n        ],\n        \"gap_ms\": 300,\n    },\n)\n\nresponse.raise_for_status()\n\n# Per-turn start/end offsets, so a client can seek to a line.\nturns = json.loads(response.headers[\"X-Turns\"])\n\nwith open(\"dialogue.wav\", \"wb\") as f:\n    f.write(response.content)"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/tts/dialogue');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'Authorization: Bearer <your-api-key>',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'turns' => [\n            ['voice_id' => '<voice-a>', 'text' => 'Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz.'],\n            ['voice_id' => '<voice-b>', 'text' => 'Xush kelibsiz! Birinchi yangilikni tinglaymiz.'],\n        ],\n        'gap_ms' => 300,\n    ]),\n]);\n\n$audio = curl_exec($ch);\ncurl_close($ch);\n\nfile_put_contents('dialogue.wav', $audio);"}]}},"/v1/tts/jobs":{"post":{"operationId":"createTtsJob","description":"Queues a synthesis and answers at once with 202 and the job, so a long text never waits on the voice. The body is exactly synthesize's. Poll `GET /api/v1/tts/jobs/{id}` until `status` is `succeeded` or `failed`, then download the audio from `GET /api/v1/tts/jobs/{id}/audio` or `audio_url`.\n\nAn obvious refusal is still immediate: 402 (`insufficient_balance` or `spend_limit_exceeded`), 403 `voice_unavailable`, and 429 `too_many_active_jobs` when this key or its organization already has as many active jobs as its limit allows (with `Retry-After`). An organization's total is shared by all its keys.\n\nPass an `Idempotency-Key` header (at most 191 characters) to make retries safe: a known key answers 200 with the original job and `Idempotency-Replayed: 1`, whatever its state. A job releases its key 24 hours after it finishes. The charge lands only when the job succeeds; a failed job costs nothing.","summary":"Create a synthesis job","tags":["TTS"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Makes a retry safe: the same key again answers 200 with the job it created, whatever its state, instead of queuing another. At most 191 characters, scoped to your organization, and released 24 hours after the job finishes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeSpeechRequest"}}}},"responses":{"200":{"description":"An idempotent replay: the job this `Idempotency-Key` already created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TtsJob"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"Idempotency-Replayed":{"description":"`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"202":{"description":"The queued job under `data`. The `Location` header points at it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TtsJob"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"Location":{"schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"400":{"description":"The `Idempotency-Key` is over 191 characters: `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"409":{"description":"The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"This key or its organization already has as many queued or running jobs as its limit allows: `too_many_active_jobs`, with `Retry-After: 5`. Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"char","rates":[{"label":"Default voice","value":0.3,"currency":"credits"},{"label":"Voice clone","value":0.5,"currency":"credits"}]},"security":[{"bearer":["tts:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# 1. Submit\ncurl -X POST \"https://my.neuronai.uz/api/v1/tts/jobs\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -H \"Idempotency-Key: my-unique-key-123\" \\\n  -d '{\"voice_id\": \"kamron\", \"text\": \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\", \"language\": \"uz\"}'\n\n# 2. Poll until data.status is \"succeeded\" or \"failed\"\ncurl \"https://my.neuronai.uz/api/v1/tts/jobs/<job-id>\" -H \"Authorization: Bearer <your-api-key>\"\n\n# 3. Download\ncurl \"https://my.neuronai.uz/api/v1/tts/jobs/<job-id>/audio\" -H \"Authorization: Bearer <your-api-key>\" --output speech.wav"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst job = await client.tts.jobs.create({\n    voice_id: \"kamron\",\n    text: \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n    language: \"uz\",\n});\n\nconsole.log(job.id, job.status);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\njob = client.tts.jobs.create(\n    voice_id=\"kamron\",\n    text=\"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\",\n    language=\"uz\",\n)\n\nprint(job.id, job.status)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$job = $client->tts->jobs->create([\n    'voice_id' => 'kamron',\n    'text' => 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.',\n    'language' => 'uz',\n]);\n\necho $job->id, ' ', $job->status, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const headers = { 'Authorization': 'Bearer <your-api-key>', 'Content-Type': 'application/json' };\n\nconst submitted = await fetch('https://my.neuronai.uz/api/v1/tts/jobs', {\n    method: 'POST',\n    headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },\n    body: JSON.stringify({ voice_id: 'kamron', text: 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.', language: 'uz' }),\n}).then((r) => r.json());\n\nlet job = submitted.data;\nwhile (job.status === 'queued' || job.status === 'running') {\n    await new Promise((resolve) => setTimeout(resolve, 2000));\n    job = (await fetch(`https://my.neuronai.uz/api/v1/tts/jobs/${job.id}`, { headers }).then((r) => r.json())).data;\n}\n\nif (job.status === 'failed') throw new Error(job.error.message);\n\nconst audio = await fetch(job.audio_url, { headers }).then((r) => r.blob());"},{"lang":"python","label":"Python","source":"import time, uuid, requests\n\nheaders = {\"Authorization\": \"Bearer <your-api-key>\"}\n\njob = requests.post(\n    \"https://my.neuronai.uz/api/v1/tts/jobs\",\n    headers={**headers, \"Idempotency-Key\": str(uuid.uuid4())},\n    json={\"voice_id\": \"kamron\", \"text\": \"Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.\", \"language\": \"uz\"},\n).json()[\"data\"]\n\nwhile job[\"status\"] in (\"queued\", \"running\"):\n    time.sleep(2)\n    job = requests.get(f\"https://my.neuronai.uz/api/v1/tts/jobs/{job['id']}\", headers=headers).json()[\"data\"]\n\nif job[\"status\"] == \"failed\":\n    raise RuntimeError(job[\"error\"][\"message\"])\n\nwith open(\"speech.wav\", \"wb\") as f:\n    f.write(requests.get(job[\"audio_url\"], headers=headers).content)"},{"lang":"php","label":"PHP","source":"use Illuminate\\Support\\Facades\\Http;\nuse Illuminate\\Support\\Str;\n\n$api = Http::withHeaders(['Authorization' => 'Bearer <your-api-key>']);\n\n$job = $api->withHeaders(['Idempotency-Key' => (string) Str::uuid()])\n    ->post('https://my.neuronai.uz/api/v1/tts/jobs', ['voice_id' => 'kamron', 'text' => 'Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.', 'language' => 'uz'])\n    ->json('data');\n\nwhile (in_array($job['status'], ['queued', 'running'], true)) {\n    sleep(2);\n    $job = $api->get(\"https://my.neuronai.uz/api/v1/tts/jobs/{$job['id']}\")->json('data');\n}\n\nif ($job['status'] === 'failed') {\n    throw new RuntimeException($job['error']['message']);\n}\n\nfile_put_contents('speech.wav', $api->get($job['audio_url'])->body());"}]}},"/v1/tts/jobs/{id}":{"get":{"operationId":"retrieveTtsJob","description":"The job and where it stands: `queued`, `running`, `succeeded` or `failed`. A final state never changes. `cost`, `balance_after`, `latency_ms` and `audio_url` are set once it has `succeeded`; `error` (`code` and `message`) once it has `failed`. Codes: `insufficient_balance`, `voice_unavailable`, `synthesis_failed`, `storage_failed`, `queue_timeout`. None of them is charged.","summary":"Get a synthesis job","tags":["TTS"],"parameters":[{"name":"id","in":"path","required":true,"description":"The job id returned when the job was created.","schema":{"type":"string"}}],"responses":{"200":{"description":"The job under `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TtsJob"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such job in your organization: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["tts:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst job = await client.tts.jobs.retrieve(\"<job-id>\");\n\nconsole.log(job.status);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\njob = client.tts.jobs.retrieve(\"<job-id>\")\n\nprint(job.status)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$job = $client->tts->jobs->retrieve('<job-id>');\n\necho $job->status, PHP_EOL;"}]}},"/v1/tts/jobs/{id}/audio":{"get":{"operationId":"downloadTtsJobAudio","description":"The WAV of a job that has `succeeded`, with the headers synthesize sends. 409 `job_not_finished` while the job is `queued` or `running`, and 409 `job_failed` after it failed. Audio is kept for 24 hours after the job finishes; after that, 410 `audio_expired`.","summary":"Download a synthesis job's audio","tags":["TTS"],"parameters":[{"name":"id","in":"path","required":true,"description":"The job id returned when the job was created.","schema":{"type":"string"}}],"responses":{"200":{"description":"WAV audio of the synthesized speech.","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Cost":{"description":"The price billed, in credits.","schema":{"type":"number"}},"X-Balance":{"description":"Your balance after the charge, in credits.","schema":{"type":"number"}},"X-Character-Count":{"description":"The characters billed. An emotion tag counts as one.","schema":{"type":"integer"}},"X-Voice-Custom":{"description":"`1` when the voice is one of your clones, `0` for a stock voice.","schema":{"type":"string","enum":["0","1"]}},"X-Latency-Ms":{"description":"Time the voice took, in milliseconds. May have a fraction.","schema":{"type":"number"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such job in your organization: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"409":{"description":"The job is still `queued` or `running` (`job_not_finished`), or it failed (`job_failed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"410":{"description":"The audio is past its 24-hour retention: `audio_expired`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["tts:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst speech = await client.tts.jobs.audio(\"<job-id>\");\n\nawait speech.save(\"speech.wav\");"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nspeech = client.tts.jobs.audio(\"<job-id>\")\n\nspeech.save(\"speech.wav\")"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$speech = $client->tts->jobs->audio('<job-id>');\n\n$speech->save('speech.wav');"}]}},"/v1/tts/voices":{"get":{"operationId":"listVoices","description":"Lists stock voices and your organization's voice clones. `type` narrows to `stock` or `custom`; `language` filters by language. Public: without a key, or with a key that lacks `voices:read`, only stock voices come back. A key that is sent is still checked, so an invalid key answers 401 rather than the public list.\n\nStock voices come first, in their catalog order, then your organization's ready clones, newest first. `tags` is always a list.\n\nPages hold up to `limit` voices (1–100, default 50). Pass a page's `next_cursor` as `cursor` to get the next, until `next_cursor` is `null`. Cursors are opaque; don't build them.","summary":"List voices","tags":["TTS"],"parameters":[{"name":"type","in":"query","schema":{"type":["string","null"],"enum":["stock","custom",null]}},{"name":"language","in":"query","schema":{"type":["string","null"],"maxLength":16}},{"name":"limit","in":"query","schema":{"type":["integer","null"],"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":["string","null"],"maxLength":512}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string","format":"uuid"}},"required":["data","next_cursor","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"A key was sent, and it is not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`). A request without a key is not refused: it is answered as anonymous.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"A key was sent, and the client IP is not in its allowlist: `ip_not_allowed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not list its voices: `upstream_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{},{"bearer":["voices:read"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl \"https://my.neuronai.uz/api/v1/tts/voices?type=stock\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nfor await (const voice of client.voices.list({type: \"stock\"})) {\n    console.log(voice.id, voice.name);\n}"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nfor voice in client.voices.list(type=\"stock\"):\n    print(voice.id, voice.name)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\nforeach ($client->voices->list(['type' => 'stock']) as $voice) {\n    echo $voice->id, ' ', $voice->name, PHP_EOL;\n}"},{"lang":"javascript","label":"JavaScript","source":"let cursor = null;\nconst voices = [];\n\ndo {\n    const query = cursor ? `type=stock&cursor=${cursor}` : 'type=stock';\n    const response = await fetch(`https://my.neuronai.uz/api/v1/tts/voices?${query}`);\n    const { data, next_cursor: nextCursor } = await response.json();\n\n    voices.push(...data);  // each: { id, name, language, tags, type: 'stock' }\n    cursor = nextCursor;\n} while (cursor !== null);\n\nconsole.log(voices);"},{"lang":"python","label":"Python","source":"import requests\n\nvoices = []\ncursor = None\n\nwhile True:\n    params = {\"type\": \"stock\", \"cursor\": cursor} if cursor else {\"type\": \"stock\"}\n    response = requests.get(\"https://my.neuronai.uz/api/v1/tts/voices\", params=params)\n    response.raise_for_status()\n\n    body = response.json()\n    voices.extend(body[\"data\"])  # each: { id, name, language, tags, type: 'stock' }\n\n    cursor = body[\"next_cursor\"]\n    if cursor is None:\n        break"},{"lang":"php","label":"PHP","source":"$json = file_get_contents('https://my.neuronai.uz/api/v1/tts/voices?type=stock');\n$voices = json_decode($json, true)['data'];  // each: ['id' => …, 'name' => …, 'language' => …, 'tags' => […], 'type' => 'stock']"}]},"post":{"operationId":"createVoice","description":"Creates a voice clone from a 10–15 second reference clip (`multipart/form-data`). `name`, `language`, `ref_audio` (WAV, MP3, OGG or FLAC, up to 10 MB) and `ref_text`, what the clip says word for word, are required; `tags[]` and `category` are optional, and blank tags are dropped. Use the new voice's `id` as `voice_id` when synthesizing.\n\nPass an `Idempotency-Key` (at most 191 characters) to make retries safe: a replay answers 200 with the voice as it is now, and a key whose voice was since deleted creates a new one. Voice keys are remembered indefinitely.\n\nWhether the voice service cannot be reached or refuses the sample, the answer is 502 `upstream_error` with \"Voice creation failed. Please try again later.\"; the real reason is only logged server-side, never returned to the caller.","summary":"Create a voice clone","tags":["Voice cloning"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Makes a retry safe: the same key again answers 200 with the voice it created, as it is now, instead of cloning another. At most 191 characters, scoped to your organization and kept indefinitely.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateVoiceRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"Idempotency-Replayed":{"description":"`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"400":{"description":"The `Idempotency-Key` is over 191 characters: `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"409":{"description":"The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not do it: `upstream_error`. Nothing is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{"bearer":["voices:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/tts/voices\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -F \"name=Aziza\" \\\n  -F \"language=uz\" \\\n  -F \"ref_audio=@/path/to/aziza-sample.wav\" \\\n  -F \"ref_text=Mening ismim Aziza, men sizga yordam berishga tayyorman.\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\nimport {readFile} from \"node:fs/promises\";\n\nconst client = new NeuronAI();\n\nconst voice = await client.voices.create({\n    name: \"Aziza\",\n    language: \"uz\",\n    ref_audio: {data: await readFile(\"aziza-sample.wav\"), filename: \"aziza-sample.wav\"},\n    ref_text: \"Mening ismim Aziza, men sizga yordam berishga tayyorman.\",\n});\n\nconsole.log(voice.id);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nvoice = client.voices.create(\n    name=\"Aziza\",\n    language=\"uz\",\n    ref_audio=\"aziza-sample.wav\",\n    ref_text=\"Mening ismim Aziza, men sizga yordam berishga tayyorman.\",\n)\n\nprint(voice.id)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$voice = $client->voices->create([\n    'name' => 'Aziza',\n    'language' => 'uz',\n    'ref_audio' => 'aziza-sample.wav',\n    'ref_text' => 'Mening ismim Aziza, men sizga yordam berishga tayyorman.',\n]);\n\necho $voice->id, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const form = new FormData();\nform.append('name', 'Aziza');\nform.append('language', 'uz');\nform.append('ref_audio', file);  // a File or Blob (10-15s clip)\nform.append('ref_text', 'Mening ismim Aziza, men sizga yordam berishga tayyorman.');\n\nconst response = await fetch('https://my.neuronai.uz/api/v1/tts/voices', {\n    method: 'POST',\n    headers: { 'Authorization': 'Bearer <your-api-key>' },\n    body: form,\n});\n\nconst { data } = await response.json();\nconst voiceId = data.id;  // use this as voice_id when synthesizing"},{"lang":"python","label":"Python","source":"import requests\n\nwith open(\"aziza-sample.wav\", \"rb\") as audio:\n    response = requests.post(\n        \"https://my.neuronai.uz/api/v1/tts/voices\",\n        headers={\"Authorization\": \"Bearer <your-api-key>\"},\n        data={\n            \"name\": \"Aziza\",\n            \"language\": \"uz\",\n            \"ref_text\": \"Mening ismim Aziza, men sizga yordam berishga tayyorman.\",\n        },\n        files={\"ref_audio\": audio},\n    )\n\nresponse.raise_for_status()\nvoice = response.json()[\"data\"]\nvoice_id = voice[\"id\"]  # use this as voice_id when synthesizing"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/tts/voices');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer <your-api-key>'],\n    CURLOPT_POSTFIELDS => [\n        'name' => 'Aziza',\n        'language' => 'uz',\n        'ref_text' => 'Mening ismim Aziza, men sizga yordam berishga tayyorman.',\n        'ref_audio' => new CURLFile('/path/to/aziza-sample.wav'),\n    ],\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);\n\n$voice = json_decode($response, true)['data'];\n$voiceId = $voice['id']; // use this as voice_id when synthesizing"}]}},"/v1/tts/voices/{id}":{"get":{"operationId":"retrieveVoice","description":"One voice by `id`. Stock voices are public. A voice clone needs a key with `voices:read` from its own organization; any other caller gets 404 `not_found`.","summary":"Get a voice","tags":["TTS"],"parameters":[{"name":"id","in":"path","required":true,"description":"The voice id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"A key was sent, and it is not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`). A request without a key is not refused: it is answered as anonymous.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"A key was sent, and the client IP is not in its allowlist: `ip_not_allowed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such voice for this key: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not list its voices: `upstream_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{},{"bearer":["voices:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst voice = await client.voices.retrieve(\"kamron\");\n\nconsole.log(voice.name);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nvoice = client.voices.retrieve(\"kamron\")\n\nprint(voice.name)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$voice = $client->voices->retrieve('kamron');\n\necho $voice->name, PHP_EOL;"}]},"patch":{"operationId":"updateVoice","description":"Changes a voice clone's `name`, `language`, `ref_text`, `tags` or `category` (JSON). Send only the fields to change; an omitted field is left alone. An explicit `null` or `tags: []` clears the tags. `ref_text` can be changed but not cleared. Blank tags are dropped. The clone keeps its `id`, so existing `voice_id` references keep working, and its reference clip is never touched.\n\nA change is made whole or not at all: when the voice service refuses it, nothing changes. Whenever the voice service fails, the answer is 502 `upstream_error` with a message written for people, such as \"The voice service is temporarily unavailable.\" when it cannot be reached, \"This voice is being changed; try again.\" when another change to it is still being made, or \"Voice update failed. Please try again later.\". Match on the status and `code`, not on the message.","summary":"Change a voice clone","tags":["Voice cloning"],"parameters":[{"name":"id","in":"path","required":true,"description":"The voice id.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVoiceRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such voice for this key: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not do it: `upstream_error`. Nothing changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{"bearer":["voices:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PATCH \"https://my.neuronai.uz/api/v1/tts/voices/<voice-id>\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Aziza, warm\", \"tags\": [\"warm\", \"narration\"]}'"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst voice = await client.voices.update(\"<voice-id>\", {\n    name: \"Aziza, warm\",\n    tags: [\"warm\", \"narration\"],\n});\n\nconsole.log(voice.name, voice.tags);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nvoice = client.voices.update(\"<voice-id>\", name=\"Aziza, warm\", tags=[\"warm\", \"narration\"])\n\nprint(voice.name, voice.tags)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$voice = $client->voices->update('<voice-id>', [\n    'name' => 'Aziza, warm',\n    'tags' => ['warm', 'narration'],\n]);\n\necho $voice->name, ' ', implode(', ', $voice->tags), PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/tts/voices/<voice-id>', {\n    method: 'PATCH',\n    headers: {\n        'Authorization': 'Bearer <your-api-key>',\n        'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({ name: 'Aziza, warm', tags: ['warm', 'narration'] }),\n});\n\nconst { data } = await response.json();  // data.id is unchanged"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.patch(\n    \"https://my.neuronai.uz/api/v1/tts/voices/<voice-id>\",\n    headers={\"Authorization\": \"Bearer <your-api-key>\"},\n    json={\"name\": \"Aziza, warm\", \"tags\": [\"warm\", \"narration\"]},\n)\n\nresponse.raise_for_status()\nvoice = response.json()[\"data\"]  # voice[\"id\"] is unchanged"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/tts/voices/<voice-id>');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'PATCH',\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'Authorization: Bearer <your-api-key>',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'name' => 'Aziza, warm',\n        'tags' => ['warm', 'narration'],\n    ]),\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);\n\n$voice = json_decode($response, true)['data']; // same id as before"}]},"delete":{"operationId":"deleteVoice","description":"Deletes a voice clone for good and answers 204. Stock voices cannot be deleted: like an unknown id, they answer 404 `not_found`. A 502 means the voice service could not delete it and the voice is kept, so a retry finishes the job.","summary":"Delete a voice clone","tags":["Voice cloning"],"parameters":[{"name":"id","in":"path","required":true,"description":"The voice id.","schema":{"type":"string"}}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such voice for this key: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not do it: `upstream_error`. The description above says what was kept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{"bearer":["voices:write"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nawait client.voices.delete(\"<voice-id>\");"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nclient.voices.delete(\"<voice-id>\")"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$client->voices->delete('<voice-id>');"}]}},"/v1/tts/voices/{id}/audio":{"post":{"operationId":"replaceVoiceAudio","description":"Replaces a voice clone's reference clip (`multipart/form-data`: `ref_audio`, and `ref_text` when the new clip says something else). The clone keeps its `id`. A voice that has no transcript must get one in the same request: without `ref_text`, the answer is 422 and nothing changes. The new clip takes the old one's place only once the voice service has accepted it: whenever it fails, the voice keeps its previous clip and transcript, and the answer is 502 `upstream_error` with a message written for people, such as \"The voice service is temporarily unavailable.\" when it cannot be reached, \"We couldn't save the new sample. Try again.\" when the clip cannot be used, or \"This voice is being changed; try again.\" when another change to it is still being made. Match on the status and `code`, not on the message.","summary":"Replace a voice clone's reference audio","tags":["Voice cloning"],"parameters":[{"name":"id","in":"path","required":true,"description":"The voice id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ReplaceVoiceAudioRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such voice for this key: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"502":{"description":"The voice service could not do it: `upstream_error`. Nothing changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}}}}},"security":[{"bearer":["voices:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/tts/voices/<voice-id>/audio\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -F \"ref_audio=@/path/to/sample.wav\" \\\n  -F \"ref_text=Assalomu alaykum, men sizga yordam berishga tayyorman.\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\nimport {readFile} from \"node:fs/promises\";\n\nconst client = new NeuronAI();\n\n// Replacing the clip rebuilds the voice from it, which can take minutes.\nconst voice = await client.voices.replaceAudio(\n    \"<voice-id>\",\n    {\n        ref_audio: {data: await readFile(\"sample.wav\"), filename: \"sample.wav\"},\n        ref_text: \"Assalomu alaykum, men sizga yordam berishga tayyorman.\",\n    },\n    {timeout: 15 * 60_000},\n);\n\nconsole.log(voice.id);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\n# Replacing the clip rebuilds the voice from it, which can take minutes.\nvoice = client.voices.replace_audio(\n    \"<voice-id>\",\n    ref_audio=\"sample.wav\",\n    ref_text=\"Assalomu alaykum, men sizga yordam berishga tayyorman.\",\n    timeout=15 * 60,\n)\n\nprint(voice.id)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n// Replacing the clip rebuilds the voice from it, which can take minutes.\n$voice = $client->voices->replaceAudio('<voice-id>', [\n    'ref_audio' => 'sample.wav',\n    'ref_text' => 'Assalomu alaykum, men sizga yordam berishga tayyorman.',\n], ['timeout' => 15 * 60]);\n\necho $voice->id, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const form = new FormData();\nform.append('ref_audio', file);  // a File or Blob (10–15 second clip), e.g. sample.wav\nform.append('ref_text', 'Assalomu alaykum, men sizga yordam berishga tayyorman.');\n\nconst response = await fetch('https://my.neuronai.uz/api/v1/tts/voices/<voice-id>/audio', {\n    method: 'POST',\n    headers: { 'Authorization': 'Bearer <your-api-key>' },\n    body: form,\n});\n\nconst { data } = await response.json();  // data.id is unchanged"},{"lang":"python","label":"Python","source":"import requests\n\nwith open(\"sample.wav\", \"rb\") as audio:\n    response = requests.post(\n        \"https://my.neuronai.uz/api/v1/tts/voices/<voice-id>/audio\",\n        headers={\"Authorization\": \"Bearer <your-api-key>\"},\n        data={\"ref_text\": \"Assalomu alaykum, men sizga yordam berishga tayyorman.\"},\n        files={\"ref_audio\": audio},\n    )\n\nresponse.raise_for_status()\nvoice = response.json()[\"data\"]  # voice[\"id\"] is unchanged"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/tts/voices/<voice-id>/audio');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer <your-api-key>'],\n    CURLOPT_POSTFIELDS => [\n        'ref_text' => 'Assalomu alaykum, men sizga yordam berishga tayyorman.',\n        'ref_audio' => new CURLFile('/path/to/sample.wav'),\n    ],\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);\n\n$voice = json_decode($response, true)['data']; // same id as before"}]}},"/v1/stt/transcribe":{"post":{"operationId":"createTranscription","description":"Transcribes an audio file (`multipart/form-data`): `file` is MP3, WAV, OGG, FLAC, M4A or WebM, up to 25 MB, and `language` is one of the supported codes, or `auto` to have the language detected. Answers the text, the language (the detected one for `auto`), the duration, timestamped segments, the cost and your balance after the charge. Billed by the second of audio, settled on the actual duration after the transcription; the request is refused up front only when nothing is left of the balance or the key's spend limit. Pass an `Idempotency-Key` (at most 191 characters) to make retries safe. A transcription's key is remembered indefinitely, so reuse a key only for the same file.","summary":"Transcribe audio","tags":["STT"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Makes a retry safe: the same key again returns the original transcription instead of transcribing and charging again. At most 191 characters, scoped to your organization and kept indefinitely, so reuse a key only for the same file.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateTranscriptionRequest"}}}},"responses":{"200":{"description":"The transcription under `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Transcription"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"Idempotency-Replayed":{"description":"`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"400":{"description":"The `Idempotency-Key` is over 191 characters: `invalid_request`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"409":{"description":"The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"500":{"description":"Transcription failed: `transcription_failed`. Nothing is charged. Anything else that fails unexpectedly: `server_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"second","rates":[{"label":"Standard","value":1,"currency":"credits"}]},"security":[{"bearer":["stt:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/stt/transcribe\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -F \"file=@/path/to/recording.mp3\" \\\n  -F \"language=uz\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\nimport {readFile} from \"node:fs/promises\";\n\nconst client = new NeuronAI();\n\nconst transcription = await client.stt.transcribe({\n    file: {data: await readFile(\"recording.mp3\"), filename: \"recording.mp3\"},\n    language: \"uz\",\n});\n\nconsole.log(transcription.text);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\ntranscription = client.stt.transcribe(file=\"recording.mp3\", language=\"uz\")\n\nprint(transcription.text)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$transcription = $client->stt->transcribe([\n    'file' => 'recording.mp3',\n    'language' => 'uz',\n]);\n\necho $transcription->text, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const form = new FormData();\nform.append('file', audioFile);  // File or Blob\nform.append('language', 'uz');\n\nconst response = await fetch('https://my.neuronai.uz/api/v1/stt/transcribe', {\n    method: 'POST',\n    headers: { 'Authorization': 'Bearer <your-api-key>' },\n    body: form,\n});\n\nconst { data } = await response.json();\nconsole.log(data.text);"},{"lang":"python","label":"Python","source":"import requests\n\nwith open(\"recording.mp3\", \"rb\") as audio:\n    response = requests.post(\n        \"https://my.neuronai.uz/api/v1/stt/transcribe\",\n        headers={\"Authorization\": \"Bearer <your-api-key>\"},\n        data={\"language\": \"uz\"},\n        files={\"file\": audio},\n    )\n\nresponse.raise_for_status()\ntranscript = response.json()[\"data\"][\"text\"]"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/stt/transcribe');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer <your-api-key>'],\n    CURLOPT_POSTFIELDS => [\n        'language' => 'uz',\n        'file' => new CURLFile('/path/to/recording.mp3'),\n    ],\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);\n\n$transcript = json_decode($response, true)['data']['text'];"}]}},"/v1/embeddings":{"post":{"operationId":"createEmbedding","description":"Returns a 1024-dimensional dense vector per input. OpenAI-compatible — set your OpenAI SDK's base URL to `{app}/api/v1` and use your API key. Billed per input token.","summary":"Create embeddings","tags":["Embeddings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmbeddingRequest"}}}},"responses":{"200":{"description":"One embedding per input, in the order of `input`: `index` is the position of its input, from 0. Each `embedding` is a list of floats, the only `encoding_format` served. `usage` gives the tokens the model counted; `prompt_tokens` is what is billed.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"model":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"embedding"},"index":{"type":"integer"},"embedding":{"type":"array","items":{"type":"number"}}},"required":["object","index","embedding"]}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","total_tokens"]}},"required":["object","model","data","usage"]}}},"headers":{"X-Cost":{"description":"The price billed, in credits.","schema":{"type":"number"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance for the estimated cost (`insufficient_balance`), or that cost would pass this key's monthly spend limit (`spend_limit_exceeded`). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"404":{"description":"`model` is not an embedding model this API serves: `model_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation (`invalid_request`: `error.param` names the first invalid field and `error.fields` maps each one to its message), the batch has more inputs than allowed (`batch_too_large`), an input is over the tokens the model takes (`input_too_large`), or the model refused the input (`upstream_rejected_input`), which fails again unchanged. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"The embedding model is at capacity: `upstream_rate_limited`. Nothing is charged. Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"502":{"description":"The embedding model failed or could not be reached: `upstream_error`. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"1K tokens","rates":[{"label":"Input","value":0.1,"currency":"credits"}]},"security":[{"bearer":["embeddings:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/embeddings\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"model\": \"bge-m3\",\n    \"input\": \"Toshkent bugun qanday?\"\n  }'"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst result = await client.embeddings.create({\n    model: \"bge-m3\",\n    input: \"Toshkent bugun qanday?\",\n});\n\nconsole.log(result.data[0]?.embedding.length);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nresult = client.embeddings.create(model=\"bge-m3\", input=\"Toshkent bugun qanday?\")\n\nprint(len(result.data[0].embedding))"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$result = $client->embeddings->create([\n    'model' => 'bge-m3',\n    'input' => 'Toshkent bugun qanday?',\n]);\n\necho count($result->data[0]->embedding), PHP_EOL;"},{"lang":"python","label":"Python (OpenAI SDK)","source":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://my.neuronai.uz/api/v1\", api_key=\"<your-api-key>\")\n\nresult = client.embeddings.create(\n    model=\"bge-m3\",\n    input=\"Toshkent bugun qanday?\",\n)\n\nprint(len(result.data[0].embedding))"},{"lang":"javascript","label":"JavaScript (OpenAI SDK)","source":"import OpenAI from 'openai';\n\nconst client = new OpenAI({\n  baseURL: 'https://my.neuronai.uz/api/v1',\n  apiKey: '<your-api-key>',\n});\n\nconst { data } = await client.embeddings.create({\n  model: 'bge-m3',\n  input: 'Toshkent bugun qanday?',\n});"}]}},"/v1/rerank":{"post":{"operationId":"rerank","description":"Scores each document against the query with a cross-encoder and returns them ordered by relevance. Cohere-compatible; the same handler serves `/api/v1/rerank` and `/api/v2/rerank`. Billed per token across the query and all documents.","summary":"Rerank documents","tags":["Rerank"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankRequest"}}}},"responses":{"200":{"description":"The documents ranked by `relevance_score`, highest first. `index` is a document's position in `documents`, from 0, and `document.text` repeats its text unless `return_documents` is `false`. `id` is this request's ID, the same as `X-Request-Id`. `meta.billed_units` (Cohere's shape) and `usage` (OpenAI's) count the same input tokens, which are what is billed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"relevance_score":{"type":"number"},"document":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}},"required":["index","relevance_score"]}},"meta":{"type":"object","properties":{"billed_units":{"type":"object","properties":{"search_units":{"type":"integer","const":1},"input_tokens":{"type":"integer"}},"required":["search_units","input_tokens"]}},"required":["billed_units"]},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","total_tokens"]}},"required":["id","model","results","meta","usage"]}}},"headers":{"X-Cost":{"description":"The price billed, in credits.","schema":{"type":"number"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"402":{"description":"Not enough balance for the estimated cost (`insufficient_balance`), or that cost would pass this key's monthly spend limit (`spend_limit_exceeded`). Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"404":{"description":"`model` is not a rerank model this API serves: `model_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation (`invalid_request`: `error.param` names the first invalid field and `error.fields` maps each one to its message), there are more documents than allowed (`too_many_documents`), the query and one document together are over the tokens the model takes (`input_too_large`), or the model refused the input (`upstream_rejected_input`), which fails again unchanged. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"The rerank model is at capacity: `upstream_rate_limited`. Nothing is charged. Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"502":{"description":"The rerank model failed or could not be reached: `upstream_error`. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"x-pricing":{"unit":"1K tokens","rates":[{"label":"Input","value":0.1,"currency":"credits"}]},"security":[{"bearer":["rerank:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://my.neuronai.uz/api/v1/rerank\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"model\": \"bge-reranker-v2-m3\",\n    \"query\": \"ob-havo\",\n    \"documents\": [\"Bugun havo issiq.\", \"Docker qollanmasi.\"],\n    \"top_n\": 5\n  }'"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst ranked = await client.rerank.create({\n    model: \"bge-reranker-v2-m3\",\n    query: \"ob-havo\",\n    documents: [\"Bugun havo issiq.\", \"Docker qollanmasi.\"],\n    top_n: 5,\n});\n\nfor (const result of ranked.results) {\n    console.log(result.index, result.relevance_score);\n}"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nranked = client.rerank.create(\n    model=\"bge-reranker-v2-m3\",\n    query=\"ob-havo\",\n    documents=[\"Bugun havo issiq.\", \"Docker qollanmasi.\"],\n    top_n=5,\n)\n\nfor result in ranked.results:\n    print(result.index, result.relevance_score)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$ranked = $client->rerank->create([\n    'model' => 'bge-reranker-v2-m3',\n    'query' => 'ob-havo',\n    'documents' => ['Bugun havo issiq.', 'Docker qollanmasi.'],\n    'top_n' => 5,\n]);\n\nforeach ($ranked->results as $result) {\n    echo $result->index, ' ', $result->relevance_score, PHP_EOL;\n}"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/rerank', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    Authorization: 'Bearer <your-api-key>',\n  },\n  body: JSON.stringify({\n    model: 'bge-reranker-v2-m3',\n    query: 'ob-havo',\n    documents: ['Bugun havo issiq.', 'Docker qollanmasi.'],\n    top_n: 5,\n  }),\n});\n\nconst { results } = await response.json();"}]}},"/v1/usage":{"get":{"operationId":"retrieveUsage","description":"Returns spend and request counts for the calling key's organization over the last `days` window (7, 30 or 90; default 30), grouped by service and by API key. Reading usage is free. `period.start` and `period.end` are the counted window: whole days, today included.","summary":"Get usage","tags":["Account"],"parameters":[{"name":"days","in":"query","description":"How many days to count, today included.","schema":{"type":"integer","enum":[7,30,90],"default":30}}],"responses":{"200":{"description":"Usage totals grouped by service and by API key.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"period":{"type":"object","properties":{"days":{"type":"integer"},"start":{"type":"string"},"end":{"type":"string"}},"required":["days","start","end"]},"total":{"type":"object","properties":{"requests":{"type":"integer"},"cost":{"type":"number"},"formatted_cost":{"type":"string"},"currency":{"type":"string","const":"credits"}},"required":["requests","cost","formatted_cost","currency"]},"by_service":{"type":"array","description":"One row per service used in the window, the costliest first: its code, such as\n`llm`, its name, and its requests and spend in credits.","items":{"type":"object","properties":{"service":{"type":"string"},"label":{"type":"string"},"requests":{"type":"integer"},"cost":{"type":"number"}},"required":["service","label","requests","cost"]}},"by_key":{"type":"array","description":"One row per API key used in the window, the costliest first. `id` is the key's\n`id`, as the API keys endpoints show it, or `null` for requests made from the\ndashboard.","items":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":"string"},"requests":{"type":"integer"},"cost":{"type":"number"}},"required":["id","name","requests","cost"]}}},"required":["period","total","by_service","by_key"]},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["account:read"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# Your balance, in credits\ncurl \"https://my.neuronai.uz/api/v1/balance\" \\\n  -H \"Authorization: Bearer <your-api-key>\"\n\n# Spend and request counts over the last 30 days\ncurl \"https://my.neuronai.uz/api/v1/usage?days=30\" \\\n  -H \"Authorization: Bearer <your-api-key>\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst usage = await client.account.usage({days: 30});\n\nconsole.log(usage.total, usage.by_service);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nusage = client.account.usage(days=30)\n\nprint(usage.total, usage.by_service)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$usage = $client->account->usage(['days' => 30]);\n\nprint_r($usage->total);\nprint_r($usage->by_service);"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/usage?days=30', {\n  headers: { Authorization: 'Bearer <your-api-key>' },\n});\n\nconst { data } = await response.json();\nconst { total, by_service: byService } = data;"}]}},"/v1/balance":{"get":{"operationId":"retrieveBalance","description":"Returns the remaining credits for the calling key's organization. Use it to surface a low balance before a request fails with `402`.","summary":"Get balance","tags":["Account"],"responses":{"200":{"description":"The organization's remaining balance.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"type":"number"},"formatted":{"type":"string"},"currency":{"type":"string"},"stt_price_per_second":{"type":"number","description":"Credits per second of audio transcribed, at your organization's price."},"stt_price_per_minute":{"type":"number","description":"Deprecated: use `stt_price_per_second`. The same rate, times 60.","deprecated":true},"tts_price_per_char":{"type":"number","description":"Credits per character of speech in a stock voice, at your organization's price."},"min_topup":{"type":"number"},"credit_limit":{"type":"number"}},"required":["balance","formatted","currency","stt_price_per_second","stt_price_per_minute","tts_price_per_char","min_topup","credit_limit"]},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["account:read"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# Your balance, in credits\ncurl \"https://my.neuronai.uz/api/v1/balance\" \\\n  -H \"Authorization: Bearer <your-api-key>\"\n\n# Spend and request counts over the last 30 days\ncurl \"https://my.neuronai.uz/api/v1/usage?days=30\" \\\n  -H \"Authorization: Bearer <your-api-key>\""},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst balance = await client.account.balance();\n\nconsole.log(balance.formatted);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nbalance = client.account.balance()\n\nprint(balance.formatted)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$balance = $client->account->balance();\n\necho $balance->formatted, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/usage?days=30', {\n  headers: { Authorization: 'Bearer <your-api-key>' },\n});\n\nconst { data } = await response.json();\nconst { total, by_service: byService } = data;"}]}},"/v1/api-keys":{"get":{"operationId":"listApiKeys","description":"Lists your organization's API keys, newest first, revoked ones included. Pages hold up to `limit` keys (1–100, default 50); pass a page's `next_cursor` as `cursor` to get the next. Key ids are lowercase ULIDs.","summary":"List API keys","tags":["API keys"],"parameters":[{"name":"limit","in":"query","schema":{"type":["integer","null"],"minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":["string","null"],"maxLength":512}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string","format":"uuid"}},"required":["data","next_cursor","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["api_keys:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nfor await (const key of client.apiKeys.list()) {\n    console.log(key.id, key.name, key.masked_key);\n}"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nfor key in client.api_keys.list():\n    print(key.id, key.name, key.masked_key)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\nforeach ($client->apiKeys->list() as $key) {\n    echo $key->id, ' ', $key->name, ' ', $key->masked_key, PHP_EOL;\n}"}]},"post":{"operationId":"createApiKey","description":"Creates a key. `name` (1–80 characters) and `access` (`full` or `restricted`) are required. A restricted key holds exactly the levels in `permissions`; a full key holds every product, and its `permissions` may then name only `api_keys`. `allowed_ips` is a list of addresses or CIDR ranges, and `monthly_spend_limit` is in credits per calendar month (UTC).\n\nAnswers 201 with the key and its `secret`. This is the only time the secret is ever shown, so store it now.\n\nThe new key never holds more than the calling key. A restricted caller cannot create full keys or set a product above its own level, and the caller's own `api_keys` level caps the one it grants. The new key cannot have looser limits either: if the caller expires, the new key must expire no later; if the caller has a monthly spend limit, the new key needs one no higher; and if the caller has an IP allowlist, every entry of the new key's must appear in the caller's, compared entry by entry. A violation answers 403 `insufficient_permissions`.\n\nA spend limit applies to each key on its own. A key made through the API outlives the key that made it, and per-key rate and concurrency overrides are not inherited.","summary":"Create an API key","tags":["API keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"Cache-Control":{"description":"Includes `no-store`: the answer holds the new key's secret, so no cache may keep a copy.","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the new key would hold more access, or looser limits, than the calling key allows (`insufficient_permissions`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["api_keys:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# Needs a key holding api_keys:write.\ncurl -X POST \"https://my.neuronai.uz/api/v1/api-keys\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -d '{\n    \"name\": \"CI\",\n    \"access\": \"restricted\",\n    \"permissions\": {\"tts\": \"write\"},\n    \"expires_at\": \"2030-01-01T00:00:00Z\"\n  }'\n\n# The response's data.secret is shown only this once — store it now."},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\n// Needs a key holding api_keys:write.\nconst key = await client.apiKeys.create({\n    name: \"CI\",\n    access: \"restricted\",\n    permissions: {tts: \"write\"},\n    expires_at: \"2030-01-01T00:00:00Z\",\n});\n\n// The secret is shown only this once: store it now.\nconsole.log(key.secret);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\n# Needs a key holding api_keys:write.\nkey = client.api_keys.create(\n    name=\"CI\",\n    access=\"restricted\",\n    permissions={\"tts\": \"write\"},\n    expires_at=\"2030-01-01T00:00:00Z\",\n)\n\n# The secret is shown only this once: store it now.\nprint(key.secret)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n// Needs a key holding api_keys:write.\n$key = $client->apiKeys->create([\n    'name' => 'CI',\n    'access' => 'restricted',\n    'permissions' => ['tts' => 'write'],\n    'expires_at' => '2030-01-01T00:00:00Z',\n]);\n\n// The secret is shown only this once: store it now.\necho $key->secret, PHP_EOL;"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch('https://my.neuronai.uz/api/v1/api-keys', {\n    method: 'POST',\n    headers: {\n        'Authorization': 'Bearer <your-api-key>',\n        'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n        name: 'CI',\n        access: 'restricted',\n        permissions: { tts: 'write' },\n        expires_at: '2030-01-01T00:00:00Z',\n    }),\n});\n\nconst { data } = await response.json();\n\n// Shown only this once — store it now, it cannot be retrieved again.\nconsole.log(data.secret);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    \"https://my.neuronai.uz/api/v1/api-keys\",\n    headers={\"Authorization\": \"Bearer <your-api-key>\"},\n    json={\n        \"name\": \"CI\",\n        \"access\": \"restricted\",\n        \"permissions\": {\"tts\": \"write\"},\n        \"expires_at\": \"2030-01-01T00:00:00Z\",\n    },\n)\n\nresponse.raise_for_status()\ndata = response.json()[\"data\"]\n\n# Shown only this once — store it now, it cannot be retrieved again.\nprint(data[\"secret\"])"},{"lang":"php","label":"PHP","source":"$ch = curl_init('https://my.neuronai.uz/api/v1/api-keys');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'Authorization: Bearer <your-api-key>',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'name' => 'CI',\n        'access' => 'restricted',\n        'permissions' => ['tts' => 'write'],\n        'expires_at' => '2030-01-01T00:00:00Z',\n    ]),\n]);\n\n$response = json_decode(curl_exec($ch), true);\ncurl_close($ch);\n\n// Shown only this once — store it now, it cannot be retrieved again.\necho $response['data']['secret'];"}]}},"/v1/api-keys/{id}":{"get":{"operationId":"retrieveApiKey","description":"One key by `id`. A key of another organization answers 404 `not_found`.","summary":"Get an API key","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The key id: a lowercase ULID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such key in your organization: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["api_keys:read"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst key = await client.apiKeys.retrieve(\"<key-id>\");\n\nconsole.log(key.name, key.masked_key);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nkey = client.api_keys.retrieve(\"<key-id>\")\n\nprint(key.name, key.masked_key)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$key = $client->apiKeys->retrieve('<key-id>');\n\necho $key->name, ' ', $key->masked_key, PHP_EOL;"}]},"patch":{"operationId":"updateApiKey","description":"Changes a key. Send only the fields to change: `permissions` replaces the whole map, `enabled` switches the key on or off, and `null` clears `expires_at`, `allowed_ips` or `monthly_spend_limit` — `allowed_ips: []` clears the allowlist too.\n\nA change that gives the key more power is checked as if the key were being created. More power means a higher level or full access, switching the key on, a later expiry, a higher spend limit, or a wider allowlist. So send the key's limits along with such a change. A violation answers 403 `insufficient_permissions`.\n\nAn app someone connected to the MCP server, such as Claude or ChatGPT, has a key of its own, named after the app with “(connected app)” at the end. That key keeps the name, access and permissions it was given when the app was connected: a change that sends any of them answers 422 `invalid_request`. Its description, limits, expiry and switch change like any key's.\n\nA revoked key cannot be changed: 409 `conflict`.","summary":"Change an API key","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The key id: a lowercase ULID.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"},"request_id":{"type":"string","format":"uuid"}},"required":["data","request_id"]}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), the client IP is not in its allowlist (`ip_not_allowed`), or the change would give the key more access, or looser limits, than the calling key allows (`insufficient_permissions`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"404":{"description":"No such key in your organization: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"409":{"description":"The key is revoked and cannot be changed: `conflict`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"422":{"description":"The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["api_keys:write"]}],"x-codeSamples":[{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\nconst key = await client.apiKeys.update(\"<key-id>\", {enabled: false});\n\nconsole.log(key.enabled);"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\nkey = client.api_keys.update(\"<key-id>\", enabled=False)\n\nprint(key.enabled)"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n$key = $client->apiKeys->update('<key-id>', ['enabled' => false]);\n\nvar_dump($key->enabled);"}]}},"/v1/api-keys/{id}/revoke":{"post":{"operationId":"revokeApiKey","description":"Revokes a key for good: it stops working at once and can never be switched back on. Its usage history stays. A key may revoke itself, to rotate. Revoking the key of an app connected to the MCP server also disconnects the app, ending its sign-in. Answers 204.","summary":"Revoke an API key","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The key id: a lowercase ULID.","schema":{"type":"string"}}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"401":{"description":"The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"403":{"description":"The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}}}},"404":{"description":"No such key in your organization: `not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}},"429":{"description":"Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.","schema":{"type":"integer"}}}},"default":{"description":"Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"X-Request-Id":{"description":"Identifies this request. A JSON body carries it as `request_id` too; quote it to support.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"How many of them are left this minute.","schema":{"type":"integer"}}}}},"security":[{"bearer":["api_keys:write"]}],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# Rotate a key safely: create the replacement first, move your apps to\n# its secret, and only then revoke the old key below.\ncurl -X POST \"https://my.neuronai.uz/api/v1/api-keys/<key-id>/revoke\" \\\n  -H \"Authorization: Bearer <your-api-key>\"\n# 204 No Content"},{"lang":"typescript","label":"TypeScript SDK","source":"import {NeuronAI} from \"@naiuz/sdk\";\n\nconst client = new NeuronAI();\n\n// Rotate a key safely: create the replacement first, move your apps to it, then revoke the old key.\nawait client.apiKeys.revoke(\"<key-id>\");"},{"lang":"python","label":"Python SDK","source":"from naiuz import NeuronAI\n\nclient = NeuronAI()\n\n# Rotate a key safely: create the replacement first, move your apps to it, then revoke the old key.\nclient.api_keys.revoke(\"<key-id>\")"},{"lang":"php","label":"PHP SDK","source":"$client = new \\Naiuz\\NeuronAI();\n\n// Rotate a key safely: create the replacement first, move your apps to it, then revoke the old key.\n$client->apiKeys->revoke('<key-id>');"},{"lang":"javascript","label":"JavaScript","source":"// Rotate a key safely: create the replacement first, move your apps to\n// its secret, and only then revoke the old key below.\nconst response = await fetch('https://my.neuronai.uz/api/v1/api-keys/<key-id>/revoke', {\n    method: 'POST',\n    headers: { 'Authorization': 'Bearer <your-api-key>' },\n});\n\nif (response.status !== 204) {\n    throw new Error(`Request failed: ${response.status}`);\n}"},{"lang":"python","label":"Python","source":"import requests\n\n# Rotate a key safely: create the replacement first, move your apps to\n# its secret, and only then revoke the old key below.\nresponse = requests.post(\"https://my.neuronai.uz/api/v1/api-keys/<key-id>/revoke\", headers={\"Authorization\": \"Bearer <your-api-key>\"})\nresponse.raise_for_status()  # 204 No Content"},{"lang":"php","label":"PHP","source":"// Rotate a key safely: create the replacement first, move your apps to\n// its secret, and only then revoke the old key below.\n$ch = curl_init('https://my.neuronai.uz/api/v1/api-keys/<key-id>/revoke');\n\ncurl_setopt_array($ch, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POST => true,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer <your-api-key>'],\n]);\n\ncurl_exec($ch); // 204 No Content\ncurl_close($ch);"}]}}},"components":{"securitySchemes":{"bearer":{"type":"http","description":"Send your API key as `Authorization: Bearer nai_…`.","scheme":"bearer"}},"schemas":{"CreateChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","maxLength":128},"max_tokens":{"type":["integer","null"],"minimum":1},"temperature":{"type":["number","null"],"minimum":0,"maximum":2},"top_p":{"type":["number","null"],"minimum":0,"maximum":1},"stop":{"description":"Text at which the model stops: one string, or a list of strings (OpenAI's `stop`).\nSent to the model exactly as given, byte for byte, including a string of only\nwhitespace such as `\\n`.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"stream":{"type":["boolean","null"]},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"type":"string","description":"The message's text, as one string. A list of content parts, as OpenAI also takes, is refused."}},"required":["role","content"]},"minItems":1}},"required":["model","messages"],"title":"CreateChatCompletionRequest"},"ErrorCode":{"type":"string","description":"A stable, machine-readable code. The Errors page says what each one means.","enum":["invalid_request","invalid_api_key","api_key_disabled","api_key_revoked","api_key_expired","insufficient_balance","spend_limit_exceeded","insufficient_permissions","ip_not_allowed","no_organization","voice_unavailable","forbidden","not_found","model_not_found","method_not_allowed","conflict","idempotency_conflict","gone","job_not_finished","job_failed","audio_expired","audio_too_large","input_too_large","unsupported_media_type","batch_too_large","too_many_documents","context_length_exceeded","upstream_rejected_input","rate_limit_exceeded","concurrency_limit_exceeded","upstream_rate_limited","too_many_active_jobs","server_error","synthesis_failed","transcription_failed","upstream_error","service_unavailable","storage_failed"],"x-enumDescriptions":{"invalid_request":"The request is malformed or failed validation.","invalid_api_key":"The API key is missing or not recognized.","api_key_disabled":"The API key is disabled; it can be enabled again.","api_key_revoked":"The API key was revoked and can never be used again.","api_key_expired":"The API key is past its expiry date.","insufficient_balance":"The organization's balance is too low for this request.","spend_limit_exceeded":"The request would take the API key over its monthly spend limit.","insufficient_permissions":"The API key lacks the permission this request needs.","ip_not_allowed":"The request's IP address is not on the API key's allowlist.","no_organization":"The API key belongs to a user without an organization.","voice_unavailable":"The voice_id is not usable by this account.","forbidden":"This API key is not allowed to make this request.","not_found":"The route or resource does not exist in this organization.","model_not_found":"The requested model does not exist or is not available.","method_not_allowed":"The HTTP method is not supported on this route.","conflict":"The request conflicts with the current state of the resource.","idempotency_conflict":"The Idempotency-Key was already used with a different request.","gone":"The resource is no longer available.","job_not_finished":"The TTS job has not finished yet.","job_failed":"The TTS job failed and has no audio.","audio_expired":"The TTS job's audio is past its retention window.","audio_too_large":"The audio is too large to send as an MCP resource; download it from its link.","input_too_large":"The input is over a size limit.","unsupported_media_type":"The uploaded media type is not supported.","batch_too_large":"The batch contains too many embedding inputs.","too_many_documents":"The request contains too many documents to rerank.","context_length_exceeded":"The prompt plus max_tokens exceeds the model's context length.","upstream_rejected_input":"The model server refused the input; retrying it unchanged will not succeed.","rate_limit_exceeded":"The API key's or its organization's per-minute request rate was exceeded.","concurrency_limit_exceeded":"Too many requests are in flight for this API key or its organization.","upstream_rate_limited":"The model server is at capacity; retry after a moment.","too_many_active_jobs":"Too many queued or running TTS jobs for this API key or its organization.","server_error":"An unexpected error occurred.","synthesis_failed":"Speech or dialogue generation failed; retry after a moment.","transcription_failed":"Transcription failed; retry after a moment.","upstream_error":"A model or voice service failed; retry after a moment.","service_unavailable":"A required service is temporarily unavailable.","storage_failed":"Audio was generated but could not be stored for an idempotent retry."},"title":"ErrorCode","x-enumStatuses":{"invalid_request":[400,422],"invalid_api_key":[401],"api_key_disabled":[401],"api_key_revoked":[401],"api_key_expired":[401],"insufficient_balance":[402],"spend_limit_exceeded":[402],"insufficient_permissions":[403],"ip_not_allowed":[403],"no_organization":[403],"voice_unavailable":[403],"forbidden":[403],"not_found":[404],"model_not_found":[404],"method_not_allowed":[405],"conflict":[409],"idempotency_conflict":[409],"gone":[410],"job_not_finished":[409],"job_failed":[409],"audio_expired":[410],"audio_too_large":[413],"input_too_large":[413,422],"unsupported_media_type":[415],"batch_too_large":[422],"too_many_documents":[422],"context_length_exceeded":[422],"upstream_rejected_input":[422],"rate_limit_exceeded":[429],"concurrency_limit_exceeded":[429],"upstream_rate_limited":[429],"too_many_active_jobs":[429],"server_error":[500],"synthesis_failed":[500],"transcription_failed":[500],"upstream_error":[502],"service_unavailable":[503],"storage_failed":[503]}},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"`insufficient_quota` for 402, `rate_limit_error` for 429, `server_error` for 5xx, and `invalid_request_error` for every other 4xx.","enum":["invalid_request_error","insufficient_quota","rate_limit_error","server_error"]},"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"What went wrong, written for people. Match on `code`, not on the message."},"param":{"type":["string","null"],"description":"The first invalid parameter, or `null`."},"fields":{"type":"object","description":"Validation errors only: each invalid field and its first message.","additionalProperties":{"type":"string"}}},"required":["type","code","message","param"]},"request_id":{"type":"string","format":"uuid","description":"The same ID as the `X-Request-Id` header."}},"required":["error","request_id"],"title":"ErrorEnvelope"},"SynthesizeSpeechRequest":{"type":"object","properties":{"text":{"type":"string","description":"The text to speak. Length is measured as spoken length, the\nsame measure billing uses: an emotion tag counts as one\ncharacter, however long its name is spelled.","minLength":1},"voice_id":{"type":["string","null"],"maxLength":128},"language":{"type":["string","null"],"enum":["uz","ru","en","kk","ky","tk","tg","az","tr","ug","tt","ba","hy","ka","uk","be","zh","ja","ko","mn","id","vi","th","hi","bn","ur","fa","arb","de","fr","es","pt","it","nl","sv","pl",null]},"quality":{"type":["string","null"],"enum":["fast","standard","high",null]},"speed":{"type":["number","null"],"minimum":0.5,"maximum":2}},"required":["text"],"title":"SynthesizeSpeechRequest"},"SynthesizeDialogueRequest":{"type":"object","properties":{"language":{"type":["string","null"],"enum":["uz","ru","en","kk","ky","tk","tg","az","tr","ug","tt","ba","hy","ka","uk","be","zh","ja","ko","mn","id","vi","th","hi","bn","ur","fa","arb","de","fr","es","pt","it","nl","sv","pl",null]},"gap_ms":{"type":["integer","null"],"minimum":0,"maximum":5000},"quality":{"type":["string","null"],"enum":["fast","standard","high",null]},"speed":{"type":["number","null"],"minimum":0.5,"maximum":2},"turns":{"type":"array","items":{"type":"object","properties":{"voice_id":{"type":"string","maxLength":128},"text":{"type":"string","description":"The turn's text. Length is measured as spoken length, the same\nmeasure billing uses: an emotion tag counts as one character,\nhowever long its name is spelled.","minLength":1},"language":{"type":["string","null"],"enum":["uz","ru","en","kk","ky","tk","tg","az","tr","ug","tt","ba","hy","ka","uk","be","zh","ja","ko","mn","id","vi","th","hi","bn","ur","fa","arb","de","fr","es","pt","it","nl","sv","pl",null]},"quality":{"type":["string","null"],"enum":["fast","standard","high",null]},"speed":{"type":["number","null"],"minimum":0.5,"maximum":2}},"required":["voice_id","text"]},"minItems":1,"maxItems":100}},"required":["turns"],"title":"SynthesizeDialogueRequest"},"TtsJobStatus":{"type":"string","enum":["queued","running","succeeded","failed"],"title":"TtsJobStatus"},"TtsJob":{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/TtsJobStatus"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time","description":"When a worker started on the job, or `null` while it is queued."},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the job succeeded or failed, or `null` until then."},"character_count":{"type":"integer"},"cost":{"type":["number","null"]},"balance_after":{"type":["number","null"]},"voice_custom":{"type":"boolean"},"latency_ms":{"type":["number","null"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"audio_url":{"type":["string","null"]}},"required":["id","status","created_at","started_at","finished_at","character_count","cost","balance_after","voice_custom","latency_ms","error","audio_url"],"title":"TtsJob"},"Voice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["custom","stock"]},"category":{"type":["string","null"]},"ref_text":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","language","tags","type"],"title":"Voice"},"VoiceCategory":{"type":"string","enum":["conversational","narration","characters","social_media","educational"],"title":"VoiceCategory"},"CreateVoiceRequest":{"type":"object","description":"The voice clone to create: its name, its language and a reference clip, and\noptionally the clip's transcript, tags and category.","properties":{"name":{"type":"string","maxLength":120},"language":{"type":"string","enum":["uz","ru","en","kk","ky","tk","tg","az","tr","ug","tt","ba","hy","ka","uk","be","zh","ja","ko","mn","id","vi","th","hi","bn","ur","fa","arb","de","fr","es","pt","it","nl","sv","pl"]},"ref_audio":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"At most 10 MB."},"ref_text":{"type":"string","maxLength":1000},"category":{"$ref":"#/components/schemas/VoiceCategory"},"tags":{"type":["array","null"],"description":"Send each tag as its own `tags[]` field. Blank tags are dropped.","items":{"type":"string","maxLength":32}}},"required":["name","language","ref_audio","ref_text"],"title":"CreateVoiceRequest"},"UpdateVoiceRequest":{"type":"object","description":"The fields to change, as JSON; every one is optional. A new reference clip\ngoes through `POST /v1/tts/voices/{id}/audio` instead.","properties":{"name":{"type":"string","maxLength":120},"category":{"$ref":"#/components/schemas/VoiceCategory"},"language":{"type":"string","enum":["uz","ru","en","kk","ky","tk","tg","az","tr","ug","tt","ba","hy","ka","uk","be","zh","ja","ko","mn","id","vi","th","hi","bn","ur","fa","arb","de","fr","es","pt","it","nl","sv","pl"]},"ref_text":{"type":"string","maxLength":1000},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":32}}},"title":"UpdateVoiceRequest"},"ReplaceVoiceAudioRequest":{"type":"object","description":"POST /v1/tts/voices/{id}/audio: a new reference sample, multipart, and\noptionally its transcript. It uses the same formats and size limit as\ncreating a clone.","properties":{"ref_audio":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"At most 10 MB."},"ref_text":{"type":"string","maxLength":1000}},"required":["ref_audio"],"title":"ReplaceVoiceAudioRequest"},"CreateTranscriptionRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"At most 25 MB."},"language":{"type":"string","enum":["auto","uz","kaa","ru","en","kk","tk","tg","tr","az","ja","de","ko"]}},"required":["file","language"],"title":"CreateTranscriptionRequest"},"Transcription":{"type":"object","properties":{"text":{"type":"string"},"language":{"type":"string"},"duration_seconds":{"type":"number"},"segments":{"type":"array","description":"The text in timed pieces, in order: where each starts and ends in\nthe audio, in seconds, and what was said.","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"}},"required":["start","end","text"]}},"cost":{"type":"number"},"balance":{"type":"number"}},"required":["text","language","duration_seconds","segments","cost","balance"],"title":"Transcription"},"CreateEmbeddingRequest":{"type":"object","properties":{"model":{"type":"string","maxLength":128},"encoding_format":{"type":["string","null"],"description":"Only float vectors are served; base64 is an OpenAI option we do not support.","enum":["float",null]},"input":{"description":"The text to embed: one string, or a list of strings for a batch.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["model","input"],"title":"CreateEmbeddingRequest"},"RerankRequest":{"type":"object","properties":{"model":{"type":"string","maxLength":128},"query":{"type":"string"},"top_n":{"type":["integer","null"],"minimum":1},"return_documents":{"type":["boolean","null"]},"documents":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["model","query","documents"],"title":"RerankRequest"},"ApiKeyAccess":{"type":"string","description":"How much a key may do. A `full` key holds every product at its highest level, products added later included, but never `api_keys`, which is only ever granted explicitly. A `restricted` key holds exactly the levels in its `permissions` map.\n","enum":["full","restricted"],"title":"ApiKeyAccess"},"ApiKey":{"type":"object","properties":{"id":{"type":"string","description":"A lowercase ULID."},"name":{"type":"string"},"description":{"type":["string","null"]},"masked_key":{"type":"string","description":"`nai_...` and the last four characters of the secret."},"access":{"$ref":"#/components/schemas/ApiKeyAccess"},"permissions":{"type":"object","description":"The effective level for every product. A full key reads as what it can do; `api_keys` is only ever granted explicitly.","properties":{"tts":{"type":"string","enum":["none","read","write"]},"voices":{"type":"string","enum":["none","read","write"]},"stt":{"type":"string","enum":["none","write"]},"llm":{"type":"string","enum":["none","read","write"]},"embeddings":{"type":"string","enum":["none","write"]},"rerank":{"type":"string","enum":["none","write"]},"account":{"type":"string","enum":["none","read"]},"api_keys":{"type":"string","enum":["none","read","write"]}},"required":["tts","voices","stt","llm","embeddings","rerank","account","api_keys"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the key stops working, or `null` for never."},"allowed_ips":{"type":"array","description":"Addresses or CIDR ranges the key may be used from. Empty allows any address.","items":{"type":"string"}},"monthly_spend_limit":{"type":["number","null"],"description":"Credits per calendar month (UTC), or `null` for no limit."},"spent_this_month":{"type":"number","description":"Credits spent this calendar month (UTC)."},"enabled":{"type":"boolean"},"revoked_at":{"type":["string","null"],"format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The whole key. Only in the answer to a create, and never again."}},"required":["id","name","description","masked_key","access","permissions","expires_at","allowed_ips","monthly_spend_limit","spent_this_month","enabled","revoked_at","last_used_at","created_at"],"title":"ApiKey"},"CreateApiKeyRequest":{"type":"object","description":"The key to create. `name` and `access` are required, so every key states\nwhat it may do; everything else is optional.","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":["string","null"],"maxLength":500},"access":{"$ref":"#/components/schemas/ApiKeyAccess"},"permissions":{"type":"object","description":"Levels by product, such as `{\"tts\": \"write\"}`. On a `restricted` key a product left out is `none`. A `full` key already holds every other product at its highest level, so its map may name only `api_keys`.","properties":{"tts":{"type":"string","enum":["none","read","write"]},"voices":{"type":"string","enum":["none","read","write"]},"stt":{"type":"string","enum":["none","write"]},"llm":{"type":"string","enum":["none","read","write"]},"embeddings":{"type":"string","enum":["none","write"]},"rerank":{"type":"string","enum":["none","write"]},"account":{"type":"string","enum":["none","read"]},"api_keys":{"type":"string","enum":["none","read","write"]}}},"expires_at":{"type":["string","null"],"format":"date-time"},"monthly_spend_limit":{"type":["number","null"],"description":"In credits per calendar month (UTC), from 0 to 999999999999.99 with at\nmost two decimals. Leave it out, or send `null`, for no limit."},"allowed_ips":{"type":["array","null"],"items":{"type":"string"},"maxItems":100}},"required":["name","access"],"title":"CreateApiKeyRequest"},"UpdateApiKeyRequest":{"type":"object","description":"The fields to change; a field left out stays as it is. `permissions`\nreplaces the whole map, and `null` clears the expiry, the allowlist or the\nspend limit.","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":["string","null"],"maxLength":500},"access":{"$ref":"#/components/schemas/ApiKeyAccess"},"permissions":{"type":"object","description":"Replaces the whole map. Levels by product, such as `{\"tts\": \"write\"}`. On a `restricted` key a product left out is `none`. A `full` key already holds every other product at its highest level, so its map may name only `api_keys`.","properties":{"tts":{"type":"string","enum":["none","read","write"]},"voices":{"type":"string","enum":["none","read","write"]},"stt":{"type":"string","enum":["none","write"]},"llm":{"type":"string","enum":["none","read","write"]},"embeddings":{"type":"string","enum":["none","write"]},"rerank":{"type":"string","enum":["none","write"]},"account":{"type":"string","enum":["none","read"]},"api_keys":{"type":"string","enum":["none","read","write"]}}},"expires_at":{"type":["string","null"],"format":"date-time"},"monthly_spend_limit":{"type":["number","null"],"description":"In credits per calendar month (UTC), from 0 to 999999999999.99 with at\nmost two decimals. `null` removes the limit."},"enabled":{"type":"boolean"},"allowed_ips":{"type":["array","null"],"items":{"type":"string"},"maxItems":100}},"title":"UpdateApiKeyRequest"}}}}
