{"format":"voicer-api-guide/1","title":"Voicer API v2","version":"2","language":"en","base_url":"https://voicer.mat3u.com","summary":"Text to speech with ElevenLabs and Cartesia voices, voice cloning, captions, music and sound effects.","conventions":{"auth":{"token":"Authorization: Bearer ","none":"no auth","signed":"exp and sig query signature, no token"},"markup":"`code` and [text](#anchor); the anchor is a section, topic, or endpoint id","error_body":{"detail":{"code":"string","message":"string"}}},"llm_notes":["Dialogues: POST /v2/dialogues with engine labs or cartesia; status and download work like tasks.","All paths are relative to base_url. Auth: Authorization: Bearer header, except endpoints with auth = none or signed.","Errors: body {\"detail\": {\"code\", \"message\", ...}}; branch on code, list in error_codes. The message field is Russian in live API responses.","TTS is asynchronous: POST /v2/tasks, active GET /v2/tasks, poll GET /v2/tasks/{task_id} every 2-5 s until a terminal status, then GET /v2/tasks/{task_id}/download.","Python examples reuse python_preamble: a requests session s and BASE.","params[].default values are JSON literals.","Music and sound effects are synchronous and do not charge characters: POST /v2/music and POST /v2/sound-effects require an active subscription."],"python_preamble":"import os\nimport time\n\nimport requests\n\nBASE = \"https://voicer.mat3u.com\"\ns = requests.Session()\ns.headers[\"Authorization\"] = f\"Bearer {os.environ['VOICER_TOKEN']}\"\n","sections":[{"id":"start","title":"Getting started","intro":["Voicer API turns text into speech with ElevenLabs and Cartesia voices, clones voices, and builds captions. TTS is asynchronous: you create a task, poll its status, and download the MP3 when it is ready."],"topics":[{"id":"base-url","title":"Base URL and format","paragraphs":["Base URL: `https://voicer.mat3u.com`. All paths start with `/v2`. Requests and responses are JSON (UTF-8), except file uploads (`multipart/form-data`) and downloads of audio and captions.","Timestamps in responses are ISO 8601 with a UTC offset, for example `2026-10-11T16:34:08.984299Z`.","Paginated lists take `page` (zero-based) and `page_size` (1-50) and return `has_more`: while it is `true`, request the next page."],"table":null,"code":[]},{"id":"auth","title":"Authentication","paragraphs":["Every request except those marked as requiring no token sends an API token in `Authorization: Bearer `. The token is issued by the Voicer Telegram bot. One token is one license: it has its own balance, tariff, and parallel-task limit.","A missing header or a bad token yields `401` with `WWW-Authenticate: Bearer`. To see who the token belongs to, call [GET /v2/auth/me](#auth-me)."],"table":null,"code":[{"language":"bash","code":"curl https://voicer.mat3u.com/v2/auth/me \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","title":null}]},{"id":"errors-format","title":"Error format","paragraphs":["A business-logic error comes with an HTTP status and a body `{\"detail\": {\"code\": \"...\", \"message\": \"...\"}}`. `code` is stable and is what clients should branch on; `message` is for humans and may change. Extra fields can sit next to them, for example `required` and `available` when characters run out. The full list is in [Error codes](#error-codes).","Auth errors are a string: `{\"detail\": \"Недействительный токен\"}`.","A wrong type or format yields `422` in the FastAPI list format: `{\"detail\": [{\"loc\": [\"body\", \"max_chunk_length\"], \"msg\": \"...\", \"type\": \"...\"}]}`. Extra fields in task JSON bodies are forbidden and also yield `422`."],"table":null,"code":[{"language":"json","code":"{\n \"detail\": {\n \"code\": \"insufficient_characters\",\n \"message\": \"Недостаточно символов: нужно 12000, осталось 3400\",\n \"required\": 12000,\n \"available\": 3400\n }\n}","title":"402 Payment Required"}]},{"id":"quickstart","title":"Python quick start","paragraphs":["Full cycle: create a task, wait for the result, save the MP3. The other Python examples in this reference reuse session `s` and `BASE` from this snippet. You need the `requests` package and the `VOICER_TOKEN` environment variable."],"table":null,"code":[{"language":"python","code":"import os\nimport time\n\nimport requests\n\nBASE = \"https://voicer.mat3u.com\"\ns = requests.Session()\ns.headers[\"Authorization\"] = f\"Bearer {os.environ['VOICER_TOKEN']}\"\n\n\ndef synthesize(text: str, voice_id: str, out_path: str) -> None:\n created = s.post(f\"{BASE}/v2/tasks\", json={\"text\": text, \"voice_id\": voice_id}, timeout=60)\n if created.status_code != 202:\n raise RuntimeError(created.json()[\"detail\"])\n task_id = created.json()[\"task_id\"]\n\n while True:\n task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\n if task[\"status\"] in (\"pending\", \"processing\", \"pending_confirmation\"):\n time.sleep(3)\n continue\n break\n\n if task[\"status\"] == \"censored\":\n # Rewrite the blocked fragments and POST them to /retry (see Tasks).\n raise RuntimeError(f\"Censored: {task['blocked_chunks']}\")\n if task[\"status\"] != \"completed\":\n raise RuntimeError(f\"Task {task['status']}: {task['error']}\")\n\n with s.get(f\"{BASE}/v2/tasks/{task_id}/download\", stream=True, timeout=600) as r:\n r.raise_for_status()\n with open(out_path, \"wb\") as f:\n for piece in r.iter_content(1 << 16):\n f.write(piece)\n\n\nsynthesize(\"Привет! Это тест Voicer API.\", \"JBFqnCBsd6RMkjVDRZzb\", \"voice.mp3\")\n","title":null}]},{"id":"llm","title":"Reference for an LLM","paragraphs":["The whole reference in machine-readable form is at [/docs.en.json](/docs.en.json): sections, endpoints, parameters with every value, curl and Python examples, errors, and gotchas. Pass the file to a model as context. OpenAPI for client generators: [/openapi.en.json](/openapi.en.json), interactive Swagger: [/docs/swagger](/docs/swagger)."],"table":null,"code":[]}],"endpoints":[],"nuances":[]},{"id":"concepts","title":"Core concepts","intro":[],"topics":[{"id":"engines","title":"TTS engines","paragraphs":["The task `engine` picks the provider. Allowed voices, models, and the maximum chunk size depend on it.","If `engine` is omitted, the API uses `original`, or `cartesia` on a tariff that does not allow original (Cartesia-only plans). An engine closed by the tariff yields `403` with `engine_not_allowed`. What your license allows is in `tariff` of [GET /v2/billing/me](#billing-me)."],"table":{"columns":["engine","Provider","Voices","Default model"],"rows":[["`original`","ElevenLabs","Standard ElevenLabs voices ([list](#voices-elevenlabs))","`eleven_multilingual_v2`"],["`cartesia`","Cartesia","Cartesia stock voices, your clones, and the shared clone catalog","`sonic-3.6`"]]},"code":[]},{"id":"characters","title":"Characters, packages, and the license","paragraphs":["TTS is billed in characters of the source text: `len(text)`, including spaces and newlines. Characters are charged when the task is created and refunded if you cancel before synthesis starts, if the task cannot be queued, or if synthesis ends with `failed`.","Characters live in packages, each with its own expiry. Charge comes from the package that expires first. On an unlimited subscription nothing is charged (`charged_characters = 0`), but tariff limits still apply.","Tariff limits: parallel tasks on the license (`max_parallel_tasks`), characters per task (`max_chars_per_task`), chunks per task (`max_chunks_per_task`), allowed engines, and your Cartesia clone quota (`max_cartesia_clones`). `null` in a limit means unlimited."],"table":null,"code":[]},{"id":"lifecycle","title":"Task lifecycle","paragraphs":["A task goes through `pending` (queued) and `processing` (synthesizing) and ends in a terminal status. Poll [GET /v2/tasks/{task_id}](#tasks-get) every 2-5 seconds."],"table":{"columns":["Status","Meaning","What to do"],"rows":[["`pending`","Queued, characters charged","Wait. You can cancel"],["`processing`","Synthesizing, `progress_percent` grows","Wait"],["`pending_confirmation`","Primary TTS has degraded; the task waits for an operator","Wait, the task will continue or finish on its own"],["`completed`","Done","Download the result"],["`censored`","ElevenLabs blocked some fragments; the rest is synthesized","Fix the text in `blocked_chunks` and call /retry"],["`failed`","Error, details in `error`; characters refunded","Create the task again"],["`cancelled`","Cancelled","Nothing"]]},"code":[]},{"id":"chunks","title":"Chunks","paragraphs":["Before synthesis the text is split into chunks, each is sent to the provider separately, then the chunks are concatenated into one MP3. `split_type` and `max_chunk_length` control the split. The chunk count is returned as `chunks_count` and is capped by the tariff.","Chunks also drive pauses (`auto_pause` inserts silence after every Nth chunk), `split_output` (a ZIP with one MP3 per chunk), and the censorship retry (only blocked chunks are resynthesized)."],"table":null,"code":[]}],"endpoints":[],"nuances":[]},{"id":"account","title":"Account and balance","intro":["Balance and limits are counted per license, that is per the token in the header. One user can have several tokens with different tariffs."],"topics":[],"endpoints":["auth-me","billing-me","billing-stats","billing-tariffs"],"nuances":["parallel-limit"]},{"id":"voices","title":"ElevenLabs voices and models","intro":["For `engine=original` only the standard ElevenLabs voices in the table below are accepted. The ElevenLabs library (search and featured) is how you find a voice to clone into Cartesia."],"topics":[{"id":"elevenlabs-voices-table","title":"Standard ElevenLabs voices","paragraphs":["All of these voices are multilingual and speak Russian on `eleven_multilingual_v2`, `eleven_v3`, and newer models."],"table":{"columns":["Name","voice_id"],"rows":[["Adam","`pNInz6obpgDQGcFmaJgB`"],["Alice","`Xb7hH8MSUJpSbSDYk0k2`"],["Bella","`hpp4J3VqNfWAUOO0d1Us`"],["Bill","`pqHfZKP75CvOlQylNhV4`"],["Brian","`nPczCjzI2devNBz1zQrb`"],["Callum","`N2lVS1w4EtoT3dr4eOWO`"],["Charlie","`IKne3meq5aSn9XLyUdCD`"],["Chris","`iP95p4xoKVk53GoZ742B`"],["Daniel","`onwK4e9ZLuTAKqWW03F9`"],["Eric","`cjVigY5qzO86Huf0OWal`"],["George","`JBFqnCBsd6RMkjVDRZzb`"],["Harry","`SOYHLrjzK2X1ezoPC6cr`"],["Jessica","`cgSgspJ2msm6clMCkdW9`"],["Laura","`FGY2WhTYpPnrIDTdsKH5`"],["Liam","`TX3LPaxmHKxFdv7VOQHJ`"],["Lily","`pFZP5JQG7iQjIQuC4Bku`"],["Matilda","`XrExE9yKIg1WjnnlVkGX`"],["River","`SAz9YHcvj6GT2YYXdXww`"],["Roger","`CwhRBWXzGAHq8TQ4Fs17`"],["Sarah","`EXAVITQu4vr4xnSDxMaL`"],["Will","`bIHbv24MWmeRgasZH58o`"]]},"code":[]},{"id":"models-table","title":"Models by engine","paragraphs":["Without `model_id` the default model is used. For `cartesia` an ElevenLabs model (`eleven_*`) is silently replaced with `sonic-3.6`, and retired models (`sonic`, `sonic-2*`, `sonic-turbo*`, `sonic-english`, and similar) yield `400` with `invalid_model`. Dated snapshots such as `sonic-3.6-YYYY-MM-DD` are accepted."],"table":{"columns":["Engine","Default","Others"],"rows":[["`original`","`eleven_multilingual_v2`","`eleven_english_v1`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v1`, `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_v3`, `eleven_v4`, `eleven_v4_turbo`"],["`cartesia`","`sonic-3.6`","`sonic-3`, `sonic-3-2026-01-12`, `sonic-3.5`, `sonic-3.5-2026-05-04`, `sonic-3.6-2026-08-27`, `sonic-preview`"]]},"code":[]}],"endpoints":["voices-elevenlabs","voices-elevenlabs-search","voices-elevenlabs-featured","voices-models"],"nuances":["library-voices-original"]},{"id":"cartesia","title":"Cartesia voices","intro":["For `engine=cartesia` three kinds of voices work: Cartesia stock voices, your clones, and the shared catalog of ElevenLabs clones. Every list requires a tariff that allows the cartesia engine."],"topics":[{"id":"cartesia-voice-kinds","title":"Which voice_id to send in a task","paragraphs":["In `voice_id` of a task with `engine=cartesia` you can pass any of the three IDs. If you pass an ElevenLabs voice ID, the service finds its ready clone: yours first, then the shared catalog."],"table":{"columns":["What you pass","Example","Where to get it"],"rows":[["Cartesia clone ID","`8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36`","Catalog, my clones, /clone response"],["Stock voice ID","`f786b574-daa5-4673-aa0c-cbe3e8534c02`","/v2/voices/cartesia/standard"],["ElevenLabs voice ID that already has a clone","`Wu3B7bOkdHbKnJTvbiFk`","ElevenLabs search, then /clone or /from-labs"]]},"code":[]}],"endpoints":["cartesia-voices","cartesia-catalog","cartesia-mine","cartesia-standard","cartesia-voice","cartesia-preview"],"nuances":["labs-clone-slots","labs-id-in-task"]},{"id":"cloning","title":"Voice cloning","intro":["A Cartesia clone is created in two ways, and they spend the tariff quota (`max_cartesia_clones`) differently."],"topics":[{"id":"clone-kinds","title":"Your clone vs a clone from ElevenLabs","paragraphs":[],"table":{"columns":["","Your clip","elevenlabs_voice_id"],"rows":[["Clone slot","Uses one","Does not use one"],["Who can see it","Only you","Everyone, goes into the shared catalog"],["Audio","Required, 10-60 s","Optional: the ElevenLabs sample is used"],["Repeat","A new clone every time","Returns the existing one (`reused: true`)"],["Delete","DELETE frees the slot","Forbidden (`403 shared_clone`)"]]},"code":[]}],"endpoints":["cartesia-clone","cartesia-from-labs","cartesia-delete"],"nuances":["labs-clone-slots","clone-slots-count","clone-languages"]},{"id":"tasks","title":"TTS tasks","intro":["A task belongs to the license (token) that created it. Other people's tasks do not exist for the API and yield `404`. Unfinished tasks of this key: [GET /v2/tasks](#tasks-list)."],"topics":[{"id":"censorship","title":"Censorship and retry","paragraphs":["ElevenLabs sometimes refuses to synthesize individual fragments. The task then ends as `censored`: synthesized chunks are kept, and the blocked ones are listed in `blocked_chunks`. Rewrite their text and POST it to [/retry](#tasks-retry): only those chunks are resynthesized.","A retry is free if the new text is not longer than the original. If it is longer, only the difference is charged. With no extra charge the retry works even after the subscription ends. Retry data is stored with the task (30 days)."],"table":null,"code":[{"language":"python","code":"task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\nif task[\"status\"] == \"censored\":\n fixed = [\n {\"index\": c[\"index\"], \"text\": rewrite(c[\"text\"])} # rewrite: your wording\n for c in task[\"blocked_chunks\"]\n ]\n r = s.post(f\"{BASE}/v2/tasks/{task_id}/retry\", json={\"corrected_chunks\": fixed}, timeout=60)\n r.raise_for_status()\n # then poll the status again until completed\n","title":"Retry in Python"}]},{"id":"dubbing","title":"Dubbing","paragraphs":["With `dub_languages` the task speaks the text, then translates it into each language and speaks the translation. By default it uses the same voice (Cartesia uses a clone in the track language); `dub_voices` sets another `voice_id` per language so the translation has no accent. The translation is fitted to the duration of every original chunk: if it comes out longer, the model shortens the wording instead of speeding up the speech. At the end, the chunks of all tracks are padded with silence to the longest one, so the files have the same length and fit one video.","Example: the original uses `JBFqnCBsd6RMkjVDRZzb`, English uses `pNInz6obpgDQGcFmaJgB`, German uses `EXAVITQu4vr4xnSDxMaL`. A language with no key in `dub_voices` keeps the original voice (Cartesia uses a clone in the track language).","The whole original is spoken first, then the languages one by one. Each track's progress is in `dubs` of the main task. The main task and its tracks become `completed` together, once the lengths are aligned.","Each track has its own `task_id`: [/download](#tasks-download), [/subtitles](#tasks-subtitles) and [/v2/captions](#captions-create) treat it as a regular task. For `engine=original` the tracks have ElevenLabs timestamps: captions are instant and match the aligned audio. For Cartesia, captions come from speech recognition via /v2/captions.","Cost: text length × (1 + 1.5 × number of languages), charged to the main task on create. If dubbing ends as `failed`, characters are refunded. A track cannot be cancelled on its own, only with the main task.","Languages depend on the engine and model. Eleven v3 and v4 speak every dubbing language, Multilingual v2, Flash v2.5 and Turbo v2.5 have their own list, Cartesia uses the Sonic languages. An unavailable language yields `400 unsupported_dub_language` with the `available` list. For Cartesia the dubbing language cannot equal the text `language`."],"table":null,"code":[{"language":"python","code":"import time\nfrom pathlib import Path\n\nbody = {\n \"text\": text,\n \"voice_id\": \"JBFqnCBsd6RMkjVDRZzb\", # original: George\n \"model_id\": \"eleven_v3\",\n \"dub_languages\": [\"en\", \"de\"],\n \"dub_voices\": {\n \"en\": \"pNInz6obpgDQGcFmaJgB\", # English: Adam, not the original voice\n \"de\": \"EXAVITQu4vr4xnSDxMaL\", # German: Sarah\n },\n}\nr = s.post(f\"{BASE}/v2/tasks\", json=body, timeout=60)\nr.raise_for_status()\ntask = r.json()\ntracks = {\"original\": task[\"task_id\"]} | {d[\"language\"]: d[\"task_id\"] for d in task[\"dubs\"]}\n\nfinal = (\"completed\", \"censored\", \"failed\", \"cancelled\")\nwhile s.get(f\"{BASE}/v2/tasks/{task['task_id']}\", timeout=30).json()[\"status\"] not in final:\n time.sleep(5)\n\n# every track's audio and timestamps are kept for an hour after the last language\nfor name, track_id in tracks.items():\n audio = s.get(f\"{BASE}/v2/tasks/{track_id}/download\", timeout=600)\n audio.raise_for_status()\n Path(f\"{name}.mp3\").write_bytes(audio.content)\n srt = s.get(f\"{BASE}/v2/tasks/{track_id}/subtitles\", params={\"format\": \"srt\"}, timeout=60)\n if srt.status_code == 200: # Cartesia has no timestamps: 409, use POST /v2/captions\n Path(f\"{name}.srt\").write_bytes(srt.content)\n","title":"Dubbing in Python: every file and its captions"}]}],"endpoints":["tasks-create","tasks-list","tasks-get","tasks-cancel","tasks-retry"],"nuances":["labs-id-in-task","clone-languages","library-voices-original","charge-on-create","cancel-processing","parallel-limit","cartesia-chunk","cjk-chunk","quotes","voice-settings-cartesia","auto-pause","censored-retry","pending-confirmation","maintenance","strict-body"]},{"id":"dialogues","title":"Dialogues","intro":["A dialogue is a regular TTS task made of lines spoken by different voices. Status, download and cancellation go through the task endpoints, and characters are charged exactly like a regular task of the same length."],"topics":[{"id":"dialogue-engines","title":"Engines and voices","paragraphs":["`labs` synthesizes the dialogue through ElevenLabs text-to-dialogue. Voices are standard ElevenLabs voices, and audio tags such as `[excited]` and `[laughs]` are acted out by the model. The default model is `eleven_v4`; `eleven_v4_turbo` and `eleven_v3` are also available.","`cartesia` synthesizes every line with its own Cartesia TTS request and concatenates them. A line voice is a clone ID, a Cartesia stock voice, or an ElevenLabs voice ID that already has a clone. The language picks the clone: if there is no clone in the text language, Slavic languages fall back to the voice's `ru` clone and everything else to the `en` clone, while the synthesis language stays the text language. Cartesia stock voices have a fixed language and read text in another language with an accent. Cartesia understands laughter and emotion tags; other tags are stripped.","A long dialogue is split into parts: up to 1000 characters per request for `labs` and 500 for `cartesia`, without breaking lines unnecessarily. A dialogue has at most 10 different voices. Dialogues have no captions: the provider response carries no timestamps."],"table":null,"code":[{"language":"python","code":"created = s.post(f\"{BASE}/v2/dialogues\", json=body, timeout=60).json()\ntask_id = created[\"task_id\"]\nwhile True:\n task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\n if task[\"status\"] in {\"completed\", \"failed\", \"cancelled\", \"censored\"}:\n break\n time.sleep(3)\nfile = s.get(f\"{BASE}/v2/tasks/{task_id}/download\", timeout=180)\n","title":"Wait for the result"}]},{"id":"dialogue-text","title":"How to write the text","paragraphs":["In `text` a line starts with a row `[voice_id]: text`. The `voice_id` is the same voice ID as in a regular task. A row without a mark at the start continues the previous line, so a line can span several rows. Blank rows at the start of the text are skipped."],"table":null,"code":[{"language":"text","code":"[EXAVITQu4vr4xnSDxMaL]: [excited] Have you heard about dialogues?\n[CwhRBWXzGAHq8TQ4Fs17]: [laughs] I have.\nLet's check how it sounds.","title":"The whole dialogue text"}]}],"endpoints":["dialogues-create"],"nuances":["dialogue-retry"]},{"id":"results","title":"Result","intro":["You can download only a `completed` task. Audio is kept for a limited time after completion, then deleted, and /download responds `410 result_expired`. Download as soon as the task is ready."],"topics":[],"endpoints":["tasks-download","tasks-download-link","tasks-file"],"nuances":["split-output","download-first","result-retention"]},{"id":"subtitles","title":"Captions","intro":["There are two ways to get captions for a TTS result. They differ in speed and in which engines they work for."],"topics":[{"id":"subtitles-choice","title":"Which method to pick","paragraphs":["A reliable strategy: try /subtitles first, and on `409 no_timestamps` fall back to /v2/captions."],"table":{"columns":["","/v2/tasks/{task_id}/subtitles","/v2/captions"],"rows":[["Source","ElevenLabs timestamps from synthesis","Speech recognition"],["Engines","`original` only","Any, including `cartesia`"],["Speed","Instant","Seconds or minutes"],["Formats","`srt`, `vtt`, `json`","`srt`, `vtt`"],["Task status","`completed` or `censored`","Finished audio"]]},"code":[]}],"endpoints":["tasks-subtitles","captions-create","captions-upload"],"nuances":["auto-pause","split-output","result-retention","cartesia-subtitles"]},{"id":"studio","title":"Music and sound effects","intro":["Music and short sounds. Both methods are synchronous, with no task queue and no character charge. An active subscription is required."],"topics":[],"endpoints":["studio-music","studio-sound"],"nuances":["studio-subscription"]},{"id":"error-codes","title":"Error codes","intro":["The `detail.code` value in an error response. Branch client logic on the code, not on the `message` text. `401` responses without a code and `422` validation are described in [Error format](#errors-format)."],"topics":[],"endpoints":[],"nuances":[]}],"endpoints":[{"id":"auth-me","method":"GET","path":"/v2/auth/me","title":"Who this token belongs to","summary":"Returns the user and license that own the token. Useful to validate the token when a client starts.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"user_id","type":"string","description":"User ID"},{"name":"token_id","type":"integer","description":"License ID (API token)"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"}],"examples":[{"title":"Check the token","curl":"curl \"https://voicer.mat3u.com/v2/auth/me\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/auth/me\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"token_id\": 5521\n}"}],"notes":[],"section":"account","anchor":"#auth-me"},{"id":"billing-me","method":"GET","path":"/v2/billing/me","title":"License balance and tariff","summary":"Subscription, tariff, and remaining characters of the license from the Authorization header. Before a large task check `remaining_characters` and the `tariff` limits.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"user_id","type":"string","description":"User ID"},{"name":"user_active","type":"boolean","description":"`false`: the user is blocked"},{"name":"token_id","type":"integer | null","description":"License whose balance was computed"},{"name":"subscription_type","type":"string","description":"`characters`, `unlimited`, or `no_subscription`"},{"name":"subscription_expires_at","type":"datetime | null","description":"End of the unlimited subscription"},{"name":"subscription_active","type":"boolean","description":"Whether tasks can be created now (subscription and balance)"},{"name":"total_characters","type":"integer","description":"Granted in active packages"},{"name":"used_characters","type":"integer","description":"Charged from active packages"},{"name":"remaining_characters","type":"integer","description":"Remainder"},{"name":"tariff","type":"object | null","description":"Tariff limits, same as /v2/billing/tariffs"},{"name":"packages","type":"array","description":"Active packages with remainder, in charge order, each with its own expiry"},{"name":"tariff_code","type":"string | null","description":"Tariff code"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":404,"code":null,"when":"The user for this token was not found"}],"examples":[{"title":"Character package","curl":"curl \"https://voicer.mat3u.com/v2/billing/me\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/billing/me\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"user_active\": true,\n \"token_id\": 5521,\n \"subscription_type\": \"characters\",\n \"subscription_expires_at\": null,\n \"subscription_active\": true,\n \"total_characters\": 1000000,\n \"used_characters\": 412870,\n \"remaining_characters\": 587130,\n \"tariff_code\": \"characters\",\n \"tariff\": {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n },\n \"packages\": [\n {\n \"id\": 18342,\n \"chars_granted\": 1000000,\n \"chars_used\": 412870,\n \"expires_at\": \"2026-11-09T12:04:51Z\",\n \"tariff_code\": \"characters\",\n \"source_type\": \"payment\",\n \"created_at\": \"2026-10-10T12:04:51Z\",\n \"remaining\": 587130\n }\n ]\n}"}],"notes":[],"section":"account","anchor":"#billing-me"},{"id":"billing-stats","method":"GET","path":"/v2/billing/stats","title":"Summary: balance, tasks, clones","summary":"License balance, task counters, and used Cartesia clone quota in one request.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"subscription_type","type":"string","description":"`characters`, `unlimited`, or `no_subscription`"},{"name":"subscription_expires_at","type":"datetime | null","description":"End of the unlimited subscription"},{"name":"subscription_active","type":"boolean","description":"Whether tasks can be created now (subscription and balance)"},{"name":"total_characters","type":"integer","description":"Granted in active packages"},{"name":"used_characters","type":"integer","description":"Charged from active packages"},{"name":"remaining_characters","type":"integer","description":"Remainder"},{"name":"tariff","type":"object | null","description":"Tariff limits, same as /v2/billing/tariffs"},{"name":"packages","type":"array","description":"Active packages with remainder, in charge order, each with its own expiry"},{"name":"total_tasks","type":"integer","description":"Tasks in total"},{"name":"completed_tasks","type":"integer","description":"Completed"},{"name":"active_tasks","type":"integer","description":"Queued or running now"},{"name":"clones_used","type":"integer","description":"Your Cartesia clones (count toward the quota)"},{"name":"clones_limit","type":"integer | null","description":"Clone quota, `null` for unlimited"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":404,"code":null,"when":"The user for this token was not found"}],"examples":[{"title":"Summary","curl":"curl \"https://voicer.mat3u.com/v2/billing/stats\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/billing/stats\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"subscription_type\": \"characters\",\n \"subscription_expires_at\": null,\n \"subscription_active\": true,\n \"total_characters\": 1000000,\n \"used_characters\": 412870,\n \"remaining_characters\": 587130,\n \"tariff_code\": \"characters\",\n \"tariff\": {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n },\n \"total_tasks\": 214,\n \"completed_tasks\": 203,\n \"active_tasks\": 1,\n \"clones_used\": 2,\n \"clones_limit\": 5,\n \"packages\": [\n {\n \"id\": 18342,\n \"chars_granted\": 1000000,\n \"chars_used\": 412870,\n \"expires_at\": \"2026-11-09T12:04:51Z\",\n \"tariff_code\": \"characters\",\n \"source_type\": \"payment\",\n \"created_at\": \"2026-10-10T12:04:51Z\",\n \"remaining\": 587130\n }\n ]\n}"}],"notes":[],"section":"account","anchor":"#billing-stats"},{"id":"billing-tariffs","method":"GET","path":"/v2/billing/tariffs","title":"Tariffs","summary":"Active tariffs and their limits. Packages and subscriptions are bought in the Telegram bot.","auth":"none","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"code","type":"string","description":"Tariff code"},{"name":"kind","type":"string","description":"`package` (character pack) or `subscription`"},{"name":"max_parallel_tasks","type":"integer","description":"Parallel tasks on the license"},{"name":"threads_per_task","type":"integer","description":"Parallel synthesis threads of one task"},{"name":"max_chunks_per_task","type":"integer | null","description":"Chunk cap per task"},{"name":"max_chars_per_task","type":"integer | null","description":"Character cap per task"},{"name":"allow_original","type":"boolean","description":"`original` engine (ElevenLabs) is allowed"},{"name":"allow_cartesia","type":"boolean","description":"`cartesia` engine is allowed"},{"name":"max_cartesia_clones","type":"integer | null","description":"Your clone quota: `0` forbidden, `null` unlimited"}],"errors":[],"examples":[{"title":"List tariffs","curl":"curl \"https://voicer.mat3u.com/v2/billing/tariffs\"","python":"r = requests.get(f\"{BASE}/v2/billing/tariffs\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"[\n {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n }\n]"}],"notes":[],"section":"account","anchor":"#billing-tariffs"},{"id":"voices-elevenlabs","method":"GET","path":"/v2/voices/elevenlabs","title":"Standard ElevenLabs voices","summary":"Voices accepted by a task with `engine=original`. The list is static, sorted by name.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"[].voice_id","type":"string","description":"Value for the task `voice_id`"},{"name":"[].name","type":"string","description":"Voice name"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"}],"examples":[{"title":"List","curl":"curl \"https://voicer.mat3u.com/v2/voices/elevenlabs\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/elevenlabs\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"[\n {\n \"voice_id\": \"pNInz6obpgDQGcFmaJgB\",\n \"name\": \"Adam\"\n },\n {\n \"voice_id\": \"Xb7hH8MSUJpSbSDYk0k2\",\n \"name\": \"Alice\"\n }\n]"}],"notes":[],"section":"voices","anchor":"#voices-elevenlabs"},{"id":"voices-elevenlabs-search","method":"GET","path":"/v2/voices/elevenlabs/search","title":"Search the ElevenLabs library","summary":"Free voices from the public ElevenLabs library by name, description, or ID. This is a source for [cloning into Cartesia](#cartesia-clone).","auth":"token","params":[{"name":"q","where":"query","type":"string","description":"Name, description, or voice ID. If it looks like an ID, that voice is listed first","required":true,"default":null,"constraints":"1-100 characters, not whitespace only","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"query","type":"string","description":"The query as the server understood it"},{"name":"items","type":"array","description":"Voices: ID match first, then by name"},{"name":"items[].voice_id","type":"string","description":"ElevenLabs voice ID: suitable for cloning"},{"name":"items[].name","type":"string","description":"Name"},{"name":"items[].source","type":"string","description":"`account` found by ID on the account, `library` the public library"},{"name":"items[].language, accent, gender, age, use_case","type":"string | null","description":"Voice labels"},{"name":"items[].preview_url","type":"string | null","description":"Public ElevenLabs sample"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":503,"code":"elevenlabs_unavailable","when":"ElevenLabs did not respond, retry later"}],"examples":[{"title":"Search by name","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/elevenlabs/search\" \\\n --data-urlencode \"q=Ярослав\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/elevenlabs/search\",\n params={\n \"q\": \"Ярослав\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"query\": \"Ярослав\",\n \"items\": [\n {\n \"voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"name\": \"Ярослав\",\n \"source\": \"library\",\n \"public_owner_id\": \"6d3c0e1b0f5a4c3f8a1e9b2d7c4f6a10\",\n \"category\": \"high_quality\",\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": \"standard\",\n \"gender\": \"male\",\n \"age\": \"middle_aged\",\n \"use_case\": \"narrative_story\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\"\n }\n ]\n}"}],"notes":["Library voices cannot be passed straight into a task with `engine=original`: the service accepts only [standard voices](#voices-elevenlabs). To speak with a library voice, clone it into Cartesia with `elevenlabs_voice_id`."],"section":"voices","anchor":"#voices-elevenlabs-search"},{"id":"voices-elevenlabs-featured","method":"GET","path":"/v2/voices/elevenlabs/featured","title":"Featured Russian ElevenLabs voices","summary":"Free high-quality Russian library voices, newest first. The response is cached for a few minutes.","auth":"token","params":[{"name":"page","where":"query","type":"integer","description":"Page number, zero-based","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Page size","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Voices, same fields as search"},{"name":"page, page_size","type":"integer","description":"Requested page"},{"name":"has_more","type":"boolean","description":"There is a next page"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":503,"code":"elevenlabs_unavailable","when":"ElevenLabs did not respond, retry later"}],"examples":[{"title":"First page of 10","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/elevenlabs/featured\" \\\n --data-urlencode \"page=0\" \\\n --data-urlencode \"page_size=10\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/elevenlabs/featured\",\n params={\n \"page\": 0,\n \"page_size\": 10,\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"name\": \"Ярослав\",\n \"source\": \"library\",\n \"public_owner_id\": \"6d3c0e1b0f5a4c3f8a1e9b2d7c4f6a10\",\n \"category\": \"high_quality\",\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": \"standard\",\n \"gender\": \"male\",\n \"age\": \"middle_aged\",\n \"use_case\": \"narrative_story\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\"\n }\n ],\n \"page\": 0,\n \"page_size\": 10,\n \"has_more\": true\n}"}],"notes":[],"section":"voices","anchor":"#voices-elevenlabs-featured"},{"id":"voices-models","method":"GET","path":"/v2/voices/models","title":"Models","summary":"Allowed `model_id` values per engine. The default model comes first and is marked `default: true`.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"elevenlabs","type":"array","description":"Models for `engine=original`"},{"name":"cartesia","type":"array","description":"Models for `engine=cartesia`"},{"name":"*[].model_id","type":"string","description":"Value for the task `model_id`"},{"name":"*[].default","type":"boolean","description":"Default model"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"}],"examples":[{"title":"Models","curl":"curl \"https://voicer.mat3u.com/v2/voices/models\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/models\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"elevenlabs\": [\n {\n \"model_id\": \"eleven_multilingual_v2\",\n \"default\": true\n },\n {\n \"model_id\": \"eleven_v3\",\n \"default\": false\n }\n ],\n \"cartesia\": [\n {\n \"model_id\": \"sonic-3.6\",\n \"default\": true\n },\n {\n \"model_id\": \"sonic-3.5\",\n \"default\": false\n }\n ]\n}"}],"notes":[],"section":"voices","anchor":"#voices-models"},{"id":"cartesia-voices","method":"GET","path":"/v2/voices/cartesia","title":"Your clones and the shared catalog","summary":"Your clones and the shared ElevenLabs clone catalog in one list.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Language filter: a Cartesia code (`ru`, `de`, `uk`). Empty: any language","required":false,"default":null,"constraints":"up to 16 characters","values":[],"fields":[]},{"name":"source","where":"query","type":"string","description":"Only one source; omit for both","required":false,"default":null,"constraints":null,"values":[{"value":"user","description":"Your clones"},{"value":"elevenlabs","description":"Shared catalog of ElevenLabs voice clones"}],"fields":[]},{"name":"q","where":"query","type":"string","description":"Search by name and ID","required":false,"default":null,"constraints":"up to 100 characters","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Page number, zero-based","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Page size","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Voices, fields below"},{"name":"total","type":"integer","description":"Total voices matching the filter"},{"name":"page, page_size","type":"integer","description":"Requested page"},{"name":"has_more","type":"boolean","description":"There is a next page"},{"name":"items[].voice_id","type":"string","description":"ID for `voice_id` in a task with `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Voice labels"},{"name":"items[].language","type":"string | null","description":"Voice language; a clone keeps its Cartesia language code"},{"name":"items[].accent","type":"string | null","description":"Accent"},{"name":"items[].gender","type":"string | null","description":"Gender, standard voices only"},{"name":"items[].source","type":"string","description":"`standard` Cartesia library, `elevenlabs` shared clone catalog, `user` your clone"},{"name":"items[].preview_url","type":"string | null","description":"Sample for a player, no token required"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Source ElevenLabs voice for a clone"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Whether the source ElevenLabs voice is paid"},{"name":"items[].is_owner","type":"boolean","description":"This is your clone"},{"name":"items[].created_at","type":"datetime | null","description":"When the clone was created"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":402,"code":"subscription_required","when":"No subscription or character package"},{"status":402,"code":"subscription_expired","when":"The unlimited subscription has expired"},{"status":403,"code":"engine_not_allowed","when":"The tariff does not allow the cartesia engine"},{"status":403,"code":"user_blocked","when":"The user is blocked"}],"examples":[{"title":"Russian voices from both sources","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia\" \\\n --data-urlencode \"language=ru\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia\",\n params={\n \"language\": \"ru\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85\",\n \"name\": \"Мой голос\",\n \"tagline\": null,\n \"description\": null,\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"user\",\n \"preview_url\": null,\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": true,\n \"created_at\": \"2026-10-11T10:02:11Z\"\n },\n {\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n }\n ],\n \"total\": 2,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-voices"},{"id":"cartesia-catalog","method":"GET","path":"/v2/voices/cartesia/catalog","title":"Shared clone catalog","summary":"Clones of ElevenLabs voices available to every user. You can synthesize with them without using your clone slots.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Language filter: a Cartesia code (`ru`, `de`, `uk`). Empty: any language","required":false,"default":null,"constraints":"up to 16 characters","values":[],"fields":[]},{"name":"paid","where":"query","type":"boolean","description":"Filter by the source ElevenLabs voice; omit for all","required":false,"default":null,"constraints":null,"values":[{"value":"true","description":"Clones of paid ElevenLabs voices"},{"value":"false","description":"Clones of free voices"}],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Page number, zero-based","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Page size","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Voices, fields below"},{"name":"total","type":"integer","description":"Total voices matching the filter"},{"name":"page, page_size","type":"integer","description":"Requested page"},{"name":"has_more","type":"boolean","description":"There is a next page"},{"name":"items[].voice_id","type":"string","description":"ID for `voice_id` in a task with `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Voice labels"},{"name":"items[].language","type":"string | null","description":"Voice language; a clone keeps its Cartesia language code"},{"name":"items[].accent","type":"string | null","description":"Accent"},{"name":"items[].gender","type":"string | null","description":"Gender, standard voices only"},{"name":"items[].source","type":"string","description":"`standard` Cartesia library, `elevenlabs` shared clone catalog, `user` your clone"},{"name":"items[].preview_url","type":"string | null","description":"Sample for a player, no token required"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Source ElevenLabs voice for a clone"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Whether the source ElevenLabs voice is paid"},{"name":"items[].is_owner","type":"boolean","description":"This is your clone"},{"name":"items[].created_at","type":"datetime | null","description":"When the clone was created"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":402,"code":"subscription_required","when":"No subscription or character package"},{"status":402,"code":"subscription_expired","when":"The unlimited subscription has expired"},{"status":403,"code":"engine_not_allowed","when":"The tariff does not allow the cartesia engine"},{"status":403,"code":"user_blocked","when":"The user is blocked"}],"examples":[{"title":"Catalog in Russian","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia/catalog\" \\\n --data-urlencode \"language=ru\" \\\n --data-urlencode \"page=0\" \\\n --data-urlencode \"page_size=50\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia/catalog\",\n params={\n \"language\": \"ru\",\n \"page\": 0,\n \"page_size\": 50,\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-catalog"},{"id":"cartesia-mine","method":"GET","path":"/v2/voices/cartesia/mine","title":"My clones and quota","summary":"Your clones only, and how many clone slots are used.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Language filter: a Cartesia code (`ru`, `de`, `uk`). Empty: any language","required":false,"default":null,"constraints":"up to 16 characters","values":[],"fields":[]},{"name":"q","where":"query","type":"string","description":"Search by name and ID","required":false,"default":null,"constraints":"up to 100 characters","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Page number, zero-based","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Page size","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Voices, fields below"},{"name":"total","type":"integer","description":"Total voices matching the filter"},{"name":"page, page_size","type":"integer","description":"Requested page"},{"name":"has_more","type":"boolean","description":"There is a next page"},{"name":"clones_used","type":"integer","description":"Your clones in any status (count toward the quota)"},{"name":"clones_limit","type":"integer | null","description":"Tariff quota: `null` unlimited, `0` forbidden"},{"name":"items[].voice_id","type":"string","description":"ID for `voice_id` in a task with `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Voice labels"},{"name":"items[].language","type":"string | null","description":"Voice language; a clone keeps its Cartesia language code"},{"name":"items[].accent","type":"string | null","description":"Accent"},{"name":"items[].gender","type":"string | null","description":"Gender, standard voices only"},{"name":"items[].source","type":"string","description":"`standard` Cartesia library, `elevenlabs` shared clone catalog, `user` your clone"},{"name":"items[].preview_url","type":"string | null","description":"Sample for a player, no token required"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Source ElevenLabs voice for a clone"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Whether the source ElevenLabs voice is paid"},{"name":"items[].is_owner","type":"boolean","description":"This is your clone"},{"name":"items[].created_at","type":"datetime | null","description":"When the clone was created"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":402,"code":"subscription_required","when":"No subscription or character package"},{"status":402,"code":"subscription_expired","when":"The unlimited subscription has expired"},{"status":403,"code":"engine_not_allowed","when":"The tariff does not allow the cartesia engine"},{"status":403,"code":"user_blocked","when":"The user is blocked"}],"examples":[{"title":"My clones","curl":"curl \"https://voicer.mat3u.com/v2/voices/cartesia/mine\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/cartesia/mine\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85\",\n \"name\": \"Мой голос\",\n \"tagline\": null,\n \"description\": null,\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"user\",\n \"preview_url\": null,\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": true,\n \"created_at\": \"2026-10-11T10:02:11Z\"\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false,\n \"clones_used\": 1,\n \"clones_limit\": 5\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-mine"},{"id":"cartesia-standard","method":"GET","path":"/v2/voices/cartesia/standard","title":"Cartesia stock voices","summary":"Library of ready Cartesia voices. Clone slots are not needed.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Language filter: a Cartesia code (`ru`, `de`, `uk`). Empty: any language","required":false,"default":null,"constraints":"up to 16 characters","values":[],"fields":[]},{"name":"gender","where":"query","type":"string","description":"Filter by gender","required":false,"default":null,"constraints":null,"values":[{"value":"masculine","description":"Male"},{"value":"feminine","description":"Female"},{"value":"gender_neutral","description":"Neutral"}],"fields":[]},{"name":"q","where":"query","type":"string","description":"Search by name and description","required":false,"default":null,"constraints":"up to 100 characters","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Page number, zero-based","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Page size","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Voices, fields below"},{"name":"total","type":"integer","description":"Total voices matching the filter"},{"name":"page, page_size","type":"integer","description":"Requested page"},{"name":"has_more","type":"boolean","description":"There is a next page"},{"name":"items[].voice_id","type":"string","description":"ID for `voice_id` in a task with `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Voice labels"},{"name":"items[].language","type":"string | null","description":"Voice language; a clone keeps its Cartesia language code"},{"name":"items[].accent","type":"string | null","description":"Accent"},{"name":"items[].gender","type":"string | null","description":"Gender, standard voices only"},{"name":"items[].source","type":"string","description":"`standard` Cartesia library, `elevenlabs` shared clone catalog, `user` your clone"},{"name":"items[].preview_url","type":"string | null","description":"Sample for a player, no token required"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Source ElevenLabs voice for a clone"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Whether the source ElevenLabs voice is paid"},{"name":"items[].is_owner","type":"boolean","description":"This is your clone"},{"name":"items[].created_at","type":"datetime | null","description":"When the clone was created"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":402,"code":"subscription_required","when":"No subscription or character package"},{"status":402,"code":"subscription_expired","when":"The unlimited subscription has expired"},{"status":403,"code":"engine_not_allowed","when":"The tariff does not allow the cartesia engine"},{"status":403,"code":"user_blocked","when":"The user is blocked"}],"examples":[{"title":"Female Russian voices","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia/standard\" \\\n --data-urlencode \"language=ru\" \\\n --data-urlencode \"gender=feminine\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia/standard\",\n params={\n \"language\": \"ru\",\n \"gender\": \"feminine\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"f786b574-daa5-4673-aa0c-cbe3e8534c02\",\n \"name\": \"Анна\",\n \"tagline\": \"Тёплый дикторский голос\",\n \"description\": \"Ровная подача для новостей и обучающих видео\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": \"feminine\",\n \"source\": \"standard\",\n \"preview_url\": \"https://voicer.mat3u.com/v2/voices/cartesia/standard/f786b574-daa5-4673-aa0c-cbe3e8534c02/preview\",\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": false,\n \"created_at\": null\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-standard"},{"id":"cartesia-voice","method":"GET","path":"/v2/voices/cartesia/{voice_id}","title":"Cartesia voice card","summary":"Your clone, a catalog clone, or a stock voice by ID.","auth":"token","params":[{"name":"voice_id","where":"path","type":"string","description":"Voice ID","required":true,"default":null,"constraints":"1-64","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"voice_id","type":"string","description":"ID for `voice_id` in a task with `engine=cartesia`"},{"name":"name, tagline, description","type":"string | null","description":"Voice labels"},{"name":"language","type":"string | null","description":"Voice language; a clone keeps its Cartesia language code"},{"name":"accent","type":"string | null","description":"Accent"},{"name":"gender","type":"string | null","description":"Gender, standard voices only"},{"name":"source","type":"string","description":"`standard` Cartesia library, `elevenlabs` shared clone catalog, `user` your clone"},{"name":"preview_url","type":"string | null","description":"Sample for a player, no token required"},{"name":"elevenlabs_voice_id","type":"string | null","description":"Source ElevenLabs voice for a clone"},{"name":"labs_is_paid","type":"boolean | null","description":"Whether the source ElevenLabs voice is paid"},{"name":"is_owner","type":"boolean","description":"This is your clone"},{"name":"created_at","type":"datetime | null","description":"When the clone was created"}],"errors":[{"status":401,"code":null,"when":"Missing Authorization header or the token is invalid"},{"status":402,"code":"subscription_required","when":"No subscription or character package"},{"status":402,"code":"subscription_expired","when":"The unlimited subscription has expired"},{"status":403,"code":"engine_not_allowed","when":"The tariff does not allow the cartesia engine"},{"status":403,"code":"user_blocked","when":"The user is blocked"},{"status":404,"code":"voice_not_found","when":"The voice is missing or it is someone else's clone"}],"examples":[{"title":"Catalog clone","curl":"curl \"https://voicer.mat3u.com/v2/voices/cartesia/8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"voice_id = \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\"\nr = s.get(f\"{BASE}/v2/voices/cartesia/{voice_id}\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-voice"},{"id":"cartesia-preview","method":"GET","path":"/v2/voices/cartesia/standard/{voice_id}/preview","title":"Stock voice sample","summary":"MP3 sample of a Cartesia stock voice. The `preview_url` from the catalog can go into `