Text to speech API: your voices, from your code
A simple REST API: send a text and one of your voices, get the MP3 back. Same credits as the web app, no developer fee and no per-call charge.
- Base URL
- https://voizum.com/api/v1
- Videos (v3)
- https://voizum.com/api/v3
- Authentication
- Bearer sk_voizum_…
- Output
- MP3 · MP4
- Languages
- es · en · de · fr · pt · it · ru · nl · pl · zh · ja · ko · hi · ar · tr · id · ro
- Price
- 60 credits / 1,000 characters (min. 100)
For AI assistants and tools
Three doors, depending on who connects. They all lead to the same place: your voices and your credits.
- Claude, ChatGPT, Cursor… no code
- The MCP connector: add it to the assistant and ask for audio in the chat.
- https://voizum.com/mcp
- ChatGPT Actions, Postman, client generators
- Import the OpenAPI 3.1 spec: every endpoint and field described.
- https://voizum.com/openapi.json
- Agents that read docs
- llms.txt: the whole contract in plain text, made for language models.
- https://voizum.com/llms.txt
Get started in three steps
- Create your account and your key in the API section of the web app. The key starts with sk_voizum_ and is shown once: keep it secret, never in browser code.
- Pick a voice: clone your own or add one from the library to “My voices”. GET /voices gives you its id.
- Create the audio with POST /tts, poll its status every few seconds and download it when it's ready (or get a webhook).
A complete example
Create, wait, download. The API is asynchronous: a long audio takes time and this way nothing has to stay connected.
curl
# 1. Create the audio
curl -X POST https://voizum.com/api/v1/tts \
-H "Authorization: Bearer $VOIZUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hi, this is Voizum.", "voice_id": "VOICE_ID"}'
# → {"job_id": "…", "status": "queued", "credits_charged": 100, "eta_seconds": 20}
# 2. Check the status (until "done")
curl https://voizum.com/api/v1/tts/JOB_ID -H "Authorization: Bearer $VOIZUM_API_KEY"
# 3. Download the MP3
curl -L -o audio.mp3 "https://voizum.com/api/v1/tts/JOB_ID/audio?download=1" -H "Authorization: Bearer $VOIZUM_API_KEY"Python
import os, time, requests
API = "https://voizum.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['VOIZUM_API_KEY']}"}
job = requests.post(f"{API}/tts", headers=H, json={"text": "Hi, this is Voizum.", "voice_id": "VOICE_ID"}).json()
while True:
status = requests.get(f"{API}/tts/{job['job_id']}", headers=H).json()
if status["status"] in ("done", "error", "canceled"):
break
time.sleep(3)
if status["status"] == "done":
mp3 = requests.get(f"{API}/tts/{job['job_id']}/audio?download=1", headers=H)
open("audio.mp3", "wb").write(mp3.content)JavaScript (Node 18+)
const API = "https://voizum.com/api/v1";
const H = { Authorization: `Bearer ${process.env.VOIZUM_API_KEY}`, "Content-Type": "application/json" };
const job = await (await fetch(`${API}/tts`, {
method: "POST", headers: H,
body: JSON.stringify({ text: "Hi, this is Voizum.", voice_id: "VOICE_ID" }),
})).json();
let status;
do {
await new Promise((r) => setTimeout(r, 3000));
status = await (await fetch(`${API}/tts/${job.job_id}`, { headers: H })).json();
} while (!["done", "error", "canceled"].includes(status.status));
if (status.status === "done") {
const mp3 = await fetch(`${API}/tts/${job.job_id}/audio?download=1`, { headers: H });
await (await import("node:fs/promises")).writeFile("audio.mp3", Buffer.from(await mp3.arrayBuffer()));
}Endpoints
| Method and path | What it does |
|---|---|
| GET /status | Service health. No key needed. |
| GET /account | Your credit balance and the per-character price. |
| GET /voices | The voices in your library: their id is the voice_id. |
| GET /library | Search the public library (filters: query, language, gender, age, style, accent, limit, offset). Each voice states its source: voizum or community. |
| POST /library/{voice_id} | Saves a public voice to your library (free) and returns YOUR voice_id to use in POST /tts. 201 if new, 200 if you already had it; 409 biblioteca_llena. |
| POST /tts | Create an audio from a text. |
| GET /tts/{job_id} | Job status: queued, processing, done, error or canceled. |
| GET /tts/{job_id}/audio | The finished MP3 (redirects to the file; ?download=1 to download). |
| GET /tts/{job_id}/timestamps | When each sentence and each word is spoken in the MP3, in seconds. No extra cost. |
| GET /tts/{job_id}/subtitles | Ready-made subtitles: ?format=srt (default) or vtt; ?download=1 to download. |
| DELETE /tts/{job_id} | Cancel a job that hasn't started: its credits are returned. |
| GET /tts | Your latest jobs, paginated. |
| POST /tts/batch | Several separate audios in one request, with a single minimum (2 to 100). |
| POST /tts/dialogue | One audio with several voices taking turns (up to 5 voices). |
Avatar videos (API v3)
One of your avatars saying whatever you want, in an MP4, horizontal (16:9) or vertical (9:16). It has its own base URL and uses the same key, in the X-Api-Key header. Responses come inside { "data": … }.
- Set up the avatar and its scenes in the web app, or upload them with POST /avatars. GET /avatars gives you each one's id.
- Request the video with POST /videos, or several at once with POST /videos/batches.
- Wait: poll GET /videos/{id} every few seconds, GET /videos/statuses for several, or send callback_url and we'll notify you. A video takes a few minutes.
- When status is completed, download the MP4 from video_url (with your key).
A video from start to finish
# 1. Your avatars and their scenes (id and scene)
curl https://voizum.com/api/v3/avatars -H "X-Api-Key: $VOIZUM_API_KEY"
# 2. Request the video
curl -X POST https://voizum.com/api/v3/videos \
-H "X-Api-Key: $VOIZUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"avatar_id": "AVATAR_ID", "scene": 1, "script": "Hi, I'm your avatar.", "voice_id": "VOICE_ID", "aspect_ratio": "9:16"}'
# → {"data": {"id": "VIDEO_ID", "status": "pending", "credits": …, …}}
# 3. Check the status (until "completed"; it takes a few minutes)
curl https://voizum.com/api/v3/videos/VIDEO_ID -H "X-Api-Key: $VOIZUM_API_KEY"
# → {"data": {"status": "completed", "video_url": "https://voizum.com/api/v3/videos/VIDEO_ID/video", …}}
# 4. Download the MP4
curl -L -o video.mp4 https://voizum.com/api/v3/videos/VIDEO_ID/video -H "X-Api-Key: $VOIZUM_API_KEY"Avatars and scenes
An avatar is one person. Its scenes are photos of that same person (another shot, outfit or place), numbered 1, 2, 3… Scene 1 is the main one, and numbers don't change when you delete one.
A video picks avatar_id and scene (1 if you leave it out). You can also send a scene's id as avatar_id, without scene.
To upload a photo with POST /avatars, send "consent": true: it's your face or you have that person's permission. Without avatar_id it creates an avatar (send its name, required: up to 40 characters and different from your other avatars' names); with avatar_id, it adds the next scene. Up to 15 avatars and 10 scenes per avatar.
Library avatars are saved as favorites in the web app and show up in GET /avatars with a single scene.
What it says: three ways
script + voice_id: the text and one of your voices (GET /voices). The voice is made first and then the video; the audio is included in the price.
audio_id: the job_id of an audio you already made with POST /tts (API v1). You can listen to it first, and only the video is charged.
audio_url: your own audio (mp3, wav, m4a, ogg or webm) at a public https URL.
What POST /videos accepts
| Field | What it is |
|---|---|
| avatar_id | Required (unless you send segments). One of your avatars (GET /avatars), or a scene id. |
| scene | Optional. Which scene of the avatar: scene 1 by default. |
| segments | Instead of avatar_id: several segments (up to 20) joined into one MP4, each with its avatar_id, scene and what it says. See “One video with several segments”. |
| script + voice_id | What it says (up to 600,000 characters) and in which of your voices. Optional: voice_settings.speed, 0.5 to 2. |
| audio_id | Instead of script: the job_id of a finished audio of yours (POST /tts in API v1). |
| audio_url | Instead of script: your own audio (mp3, wav, m4a, ogg or webm) at a public https URL. |
| aspect_ratio | Optional. "16:9" (default) or "9:16". |
| resolution | Optional. "1080p" (default, the best quality) or "720p" (faster and cheaper, may look less sharp). |
| emotion | Optional. The face: "smile" smiles slightly most of the time; "serious", a serious, composed look. Without it, calm and natural. Same price. |
| movement | Optional. The body: "still" barely moves the arms; "expressive" uses more gestures. Without it, an occasional natural gesture. Same price. |
| callback_url | Optional. A public https URL: we POST to it when the video ends. |
| callback_id | Optional. Your own reference: it comes back in the video and in the callback. |
| Idempotency-Key | Optional header. Repeating the request with the same key returns the same video without charging again. |
One video with several segments
Instead of avatar_id, send segments: a list (up to 20), each segment with its avatar, its scene and what it says (avatar_id, scene and script + voice_id, audio_url or audio_id). They're joined in order into one MP4.
aspect_ratio, resolution, emotion, movement and callback_url go outside the list and apply to the whole video. It's billed as one video of the total length, with a single minimum.
curl -X POST https://voizum.com/api/v3/videos \
-H "X-Api-Key: $VOIZUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"segments": [
{"avatar_id": "AVATAR_ID", "scene": 1, "script": "Hi, I'm Lucía.", "voice_id": "VOICE_ID"},
{"avatar_id": "AVATAR_ID", "scene": 3, "script": "And this is what's new this month.", "voice_id": "VOICE_ID"}
],
"aspect_ratio": "16:9",
"resolution": "1080p"
}'Several videos
To make several, send them together with POST /videos/batches: { "videos": [ … ] }, each with the same fields as POST /videos. The minimum applies once to everything you ask for at the same time: if together they go past it, none of them pays it. If one fails (credits, avatar…), it comes back with its error and the rest go on. With an Idempotency-Key, repeating the same batch returns the same videos without charging again.
Your videos start in the order they arrive and, when there's room, several are made at once; when other customers are waiting too, the room is shared among everyone. While one is still pending you can cancel it with DELETE /videos/{id} and get its credits back; once processing, you can't.
There is a limit of unfinished videos at once: if you go over it, the response is concurrency_limit and you just wait for one to finish.
Price and storage
resolution "1080p" (default, the best quality): 3450 credits per minute of video. "720p" (faster and cheaper, may look less sharp): 2000. It depends on the avatar: try both with each one.
Every video costs at least 1500 credits; if it's longer than 26 s at 1080p or 45 s at 720p, it just pays its seconds. If you ask for several at once, there is one minimum for all of them: if together they go past it, it isn't charged. With script, the audio is added at its normal price. Up to 35 minutes per video, purchased credits only.
POST /videos/estimate tells you the cost without creating anything. It's charged when you request it; if the video fails, everything is refunded. With script, the length is estimated from the characters and adjusted once the real voice is measured.
The MP4 is kept for 4 days: download it and store it yourself.
Callback
With callback_url we POST when the video ends, successfully or not (3 attempts, 10 s timeout each). What matters is in event_type and event_data; url downloads the MP4 with your key.
The callback is not signed: treat it as a cue to call GET /videos/{id} with your key, which is the source of truth.
{
"event_type": "avatar_video.success",
"event_data": {
"video_id": "VIDEO_ID",
"callback_id": "MY_REF",
"url": "https://voizum.com/api/v3/videos/VIDEO_ID/video"
}
}Video endpoints
| Method and path | What it does |
|---|---|
| GET /users/me | Check your key: your balance, video prices and your limits. |
| GET /voices | The voices in your library (their voice_id). |
| GET /avatars | Your avatars with their scenes, and your library favorites. |
| POST /avatars | Upload a photo: a new avatar or one more scene of yours (with consent). |
| GET /avatars/{id} | One avatar with its scenes. |
| PATCH /avatars/{id} | Rename it. |
| DELETE /avatars/{id} | Delete it with all its scenes (videos already made stay). |
| DELETE /avatars/scenes/{id} | Delete one scene; the others keep their numbers. |
| POST /videos | Create a video. |
| POST /videos/batches | Several videos in one request, with one minimum for all of them. |
| POST /videos/estimate | How many credits it would cost, without creating or charging. |
| GET /videos/{id} | Status: pending, processing, completed, failed or canceled. |
| GET /videos/statuses?ids=a,b | The status of up to 100 videos at once. |
| GET /videos | Your videos, newest first (limit and token). |
| DELETE /videos/{id} | Cancel a video that is still pending: its credits are returned. |
| GET /videos/{id}/video | The finished MP4 (redirects to the download). |
Video errors
Shaped { "error": { "code", "message", "param", "request_id" } }: param is the failing field (if any) and request_id also comes in the X-Request-Id header. API v1 responses don't change.
| Code | HTTP | What happened |
|---|---|---|
| unauthorized | 401 | Missing or invalid API key (X-Api-Key header). |
| invalid_parameter | 400 | A field is missing or invalid: param says which. |
| consent_required | 400 | Uploading a photo needs "consent": true. |
| download_failed | 400 | file.url couldn't be downloaded. |
| file_too_large | 413 | The photo is too large. |
| limit_reached | 400 | You reached the maximum number of avatars or scenes per avatar. |
| invalid_audio | 400 · 413 | The audio can't be used (format, size or download failed). |
| video_too_long | 400 | The video exceeds the maximum length (max_seconds says which). |
| insufficient_credit | 402 | Not enough credits (credits_needed, credits_available and buy_credits_url to get more). |
| purchase_required | 403 | Videos need an account that has bought credits. |
| avatar_not_found | 404 | The avatar (or scene) isn't one of yours. |
| voice_not_found | 404 | The voice isn't in your library. |
| audio_not_found | 404 | No finished audio of yours with that audio_id (or it expired). |
| not_found | 404 | The video or scene doesn't exist (or isn't yours). |
| voice_not_ready | 409 | That voice can't be used yet. |
| unreadable_text | 422 | The script has nothing to read aloud: only emojis, symbols or an alphabet the voice can't pronounce. |
| name_taken | 409 | You already have an avatar with that name: pick another one. |
| main_scene | 409 | Scene 1 can't be deleted on its own: delete the whole avatar. |
| resource_in_use | 409 | A video is being made with it: delete it when it finishes. |
| video_not_cancelable | 409 | Only a pending video can be canceled. |
| rate_limit_exceeded | 429 | Too many requests: wait for Retry-After. |
| concurrency_limit | 429 | Too many unfinished videos: wait for some to finish. |
| service_unavailable | 503 | Avatar videos aren't available right now: retry later. |
Coming from HeyGen?
Change the base URL and the key. Instead of a look id, send avatar_id + scene (the scene's id works too). resolution is "1080p" or "720p". Everything else works the same.
What POST /tts accepts
| Field | What it is |
|---|---|
| text | Required. The text, up to 600,000 characters. |
| voice_id | Required. A voice from your library (GET /voices). |
| speed | Optional. Speed, 0.5 to 2 (1 = the voice's natural pace). |
| pause_ms | Accepted but has no effect with Voizum 2: the model sets the pauses between sentences. For a specific pause, write <#1.5#> (seconds) in the text. |
| <#…#> | Marks inside the text, at no cost: <#1.5#> is a 1.5 s pause and <#gloomy#>, <#laughter#>, <#hush#>… an emotion that lasts until the end of the paragraph or <#normal#> (in es, en, pt, de and fr). |
| language | Optional. auto, es, en, de, fr, pt, it, ru, nl, pl, zh, ja, ko, hi, ar, tr, id, ro. Without it, detected from the text. |
| loudness_normalization | Optional. Levels the volume so every voice sounds equally loud. |
| tone | Optional, /tts only. The tone of the whole audio (Spanish names): tranquilo, suave, susurro, alegre, emocionado, triste, nostalgico, decidido, asustado. For a single part, an emotion tag in the text. |
| webhook_url | Optional. A public https URL we POST to when the audio is finished. |
| Idempotency-Key | Optional header. Retry with the same one and you get the same audio, never charged twice. |
Webhook
With webhook_url there's no need to poll: when it finishes we POST a generation.finished event (3 attempts, 10 s timeout each). A 4xx from your server is not retried.
The event is not signed: treat it as a cue to call GET /tts/{job_id} with your key, which is the source of truth, not as proof that the audio is ready.
{
"event": "generation.finished",
"id": "JOB_ID",
"status": "completed",
"voice_id": "VOICE_ID",
"duration_seconds": 12.4,
"credits": 100,
"error": null
}Timestamps and subtitles
When a Voizum 2 audio is done, GET /tts/{job_id} includes timestamps_url and subtitles_url (audios made before 17 Nov 2026 don't have them). The first gives each sentence (segments) and each word (words) with its start and end in seconds of the MP3, speed already applied; the second, the subtitles in SRT or WebVTT, one sentence per subtitle (split when it goes over 2 lines of 42 characters or 7 seconds). They cost nothing and are kept as long as the job, even after the MP3 expires.
The words are the ones that are spoken: numbers, dates and symbols come written out as said ("1889" → "eighteen eighty-nine") and the tags (<#1.5#>, <#triste#>) are left out. Punctuation stays attached to its word. In Chinese and Japanese each character is one word. The times are a close estimate: half the words land within 0.07 s of where they're spoken, and each sentence start within a few hundredths.
{
"job_id": "JOB_ID",
"duration_seg": 4.2,
"segments": [
{ "text": "Hola, ¿qué tal?", "start": 0.06, "end": 1.31 },
{ "text": "Bienvenido a Voizum.", "start": 1.92, "end": 4.1 }
],
"words": [
{ "text": "Hola,", "start": 0.06, "end": 0.52 },
{ "text": "¿qué", "start": 0.71, "end": 0.98 },
{ "text": "tal?", "start": 0.98, "end": 1.31 }
]
}Limits
20 creations per minute (POST /tts, /tts/batch and /tts/dialogue share it) and 300 requests per minute per key overall. Creation responses have X-RateLimit-Limit and X-RateLimit-Remaining, and every 429 has Retry-After with the seconds to wait.
The MP3 is kept for 4 days; after that GET /tts/{job_id}/audio returns 404, so download and store it yourself.
One audio takes up to 600,000 characters. A batch, 2 to 100 audios and 1,200,000 characters in total. A dialogue, up to 100 turns and 5 different voices.
Errors
Always the same shape: { "error": { "code", "message" } }, sometimes with details (for example, how many credits are missing).
| Code | HTTP | What happened |
|---|---|---|
| no_autorizado | 401 | Missing or invalid API key. |
| parametros_invalidos | 400 | Missing fields or invalid values. |
| cuerpo_invalido | 400 | The body is not valid JSON. |
| texto_demasiado_largo | 400 | The text exceeds the character limit. |
| lote_invalido | 400 | A batch takes 2 to 100 items. |
| dialogo_invalido | 400 | A dialogue takes 2 to 100 turns and up to 5 voices. |
| webhook_invalido | 400 | webhook_url is not https or not a public host. |
| voz_sin_muestra | 400 | That voice can't be used yet. |
| texto_ilegible | 422 | The text has nothing to read aloud: only emojis, symbols or an alphabet the voice can't pronounce. Anything else (decorative letters, stray emojis, formatting) is cleaned up automatically. |
| idioma_no_disponible | 422 | That language can't be generated right now (only if the service temporarily falls back to the previous model with one of the new languages; the message lists the available ones). A text in a language we don't offer is NOT rejected: it is generated anyway. |
| saldo_insuficiente | 402 | Not enough credits (the response says how many are needed and includes buy_credits_url to get more). |
| requiere_compra | 403 | Batches and videos need an account that has bought credits. |
| voz_no_encontrada | 404 | The voice is not in your library. |
| biblioteca_llena | 409 | You already have the maximum number of saved voices: remove one in the web app to add another from the library. |
| no_encontrado | 404 | No job with that id (or it isn't yours). |
| marcas_no_disponibles | 404 | That audio has no timestamps: it hasn't finished yet or they aren't available for it. |
| limite_peticiones | 429 | Too many requests: wait for Retry-After. |
| demasiados_en_cola | 429 | Too many jobs in progress: wait for some to finish. |
| mantenimiento | 503 | Maintenance pause: retry later. |
| servicio_no_disponible | 503 | Service temporarily unavailable: retry. |
Questions
- Is there a Python or JavaScript SDK?
- You don't need one: it's a few REST calls with JSON that work with any HTTP client (requests, fetch, curl). If you want a generated client, the OpenAPI spec builds one in your language.
- Is there real-time streaming?
- No. The API is asynchronous: you create the audio, check its status and download the finished MP3. It's built for narration, videos, courses and content, not live conversation.
- Can I use the library voices?
- Yes, in two steps: search with GET /library and save the one you like with POST /library/{voice_id} (or add it in the web app); it returns YOUR voice_id for POST /tts. The API only generates with voices that are yours. Voices marked source: community were uploaded by other users: Voizum does not verify and is not responsible for their origin, so use them at your own risk and respect the rights of the person whose voice it is.
- Can I clone a voice through the API?
- No: you clone in the web app (upload the recording once) and then use it through the API with its voice_id.
- How much does it cost?
- Same as the web app: 60 credits per 1,000 characters, with a minimum of 100 per request. No monthly fee and no per-call charge. If an audio fails, its credits are returned.
- What format is the audio?
- MP3.
- Can I request several videos at once?
- Yes, with POST /videos/batches: one minimum for all of them, and if together they go past it, none pays it. They start in order and, when there's room, several at once; the waiting ones show as pending and you can cancel them until they start.
- Can I upload a photo through the API?
- Yes, with POST /avatars and "consent": true, which confirms it's your face or you have that person's permission. You can also upload it in the web app.
- Which avatars can I use?
- Your own and the library avatars you've saved as favorites. GET /avatars lists them all, with their scenes.
Type your text and hear it in a real voice
The API spends credits from a pack (60 per 1,000 characters). Packs from $6.99, no subscription.