Voizum

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

  1. 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.
  2. Pick a voice: clone your own or add one from the library to “My voices”. GET /voices gives you its id.
  3. 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 pathWhat it does
GET /statusService health. No key needed.
GET /accountYour credit balance and the per-character price.
GET /voicesThe voices in your library: their id is the voice_id.
GET /librarySearch 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 /ttsCreate an audio from a text.
GET /tts/{job_id}Job status: queued, processing, done, error or canceled.
GET /tts/{job_id}/audioThe finished MP3 (redirects to the file; ?download=1 to download).
GET /tts/{job_id}/timestampsWhen each sentence and each word is spoken in the MP3, in seconds. No extra cost.
GET /tts/{job_id}/subtitlesReady-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 /ttsYour latest jobs, paginated.
POST /tts/batchSeveral separate audios in one request, with a single minimum (2 to 100).
POST /tts/dialogueOne 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": … }.

https://voizum.com/api/v3
  1. 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.
  2. Request the video with POST /videos, or several at once with POST /videos/batches.
  3. 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.
  4. 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

FieldWhat it is
avatar_idRequired (unless you send segments). One of your avatars (GET /avatars), or a scene id.
sceneOptional. Which scene of the avatar: scene 1 by default.
segmentsInstead 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_idWhat it says (up to 600,000 characters) and in which of your voices. Optional: voice_settings.speed, 0.5 to 2.
audio_idInstead of script: the job_id of a finished audio of yours (POST /tts in API v1).
audio_urlInstead of script: your own audio (mp3, wav, m4a, ogg or webm) at a public https URL.
aspect_ratioOptional. "16:9" (default) or "9:16".
resolutionOptional. "1080p" (default, the best quality) or "720p" (faster and cheaper, may look less sharp).
emotionOptional. The face: "smile" smiles slightly most of the time; "serious", a serious, composed look. Without it, calm and natural. Same price.
movementOptional. The body: "still" barely moves the arms; "expressive" uses more gestures. Without it, an occasional natural gesture. Same price.
callback_urlOptional. A public https URL: we POST to it when the video ends.
callback_idOptional. Your own reference: it comes back in the video and in the callback.
Idempotency-KeyOptional 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 pathWhat it does
GET /users/meCheck your key: your balance, video prices and your limits.
GET /voicesThe voices in your library (their voice_id).
GET /avatarsYour avatars with their scenes, and your library favorites.
POST /avatarsUpload 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 /videosCreate a video.
POST /videos/batchesSeveral videos in one request, with one minimum for all of them.
POST /videos/estimateHow many credits it would cost, without creating or charging.
GET /videos/{id}Status: pending, processing, completed, failed or canceled.
GET /videos/statuses?ids=a,bThe status of up to 100 videos at once.
GET /videosYour videos, newest first (limit and token).
DELETE /videos/{id}Cancel a video that is still pending: its credits are returned.
GET /videos/{id}/videoThe 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.

CodeHTTPWhat happened
unauthorized401Missing or invalid API key (X-Api-Key header).
invalid_parameter400A field is missing or invalid: param says which.
consent_required400Uploading a photo needs "consent": true.
download_failed400file.url couldn't be downloaded.
file_too_large413The photo is too large.
limit_reached400You reached the maximum number of avatars or scenes per avatar.
invalid_audio400 · 413The audio can't be used (format, size or download failed).
video_too_long400The video exceeds the maximum length (max_seconds says which).
insufficient_credit402Not enough credits (credits_needed, credits_available and buy_credits_url to get more).
purchase_required403Videos need an account that has bought credits.
avatar_not_found404The avatar (or scene) isn't one of yours.
voice_not_found404The voice isn't in your library.
audio_not_found404No finished audio of yours with that audio_id (or it expired).
not_found404The video or scene doesn't exist (or isn't yours).
voice_not_ready409That voice can't be used yet.
unreadable_text422The script has nothing to read aloud: only emojis, symbols or an alphabet the voice can't pronounce.
name_taken409You already have an avatar with that name: pick another one.
main_scene409Scene 1 can't be deleted on its own: delete the whole avatar.
resource_in_use409A video is being made with it: delete it when it finishes.
video_not_cancelable409Only a pending video can be canceled.
rate_limit_exceeded429Too many requests: wait for Retry-After.
concurrency_limit429Too many unfinished videos: wait for some to finish.
service_unavailable503Avatar 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

FieldWhat it is
textRequired. The text, up to 600,000 characters.
voice_idRequired. A voice from your library (GET /voices).
speedOptional. Speed, 0.5 to 2 (1 = the voice's natural pace).
pause_msAccepted 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).
languageOptional. 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_normalizationOptional. Levels the volume so every voice sounds equally loud.
toneOptional, /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_urlOptional. A public https URL we POST to when the audio is finished.
Idempotency-KeyOptional 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).

CodeHTTPWhat happened
no_autorizado401Missing or invalid API key.
parametros_invalidos400Missing fields or invalid values.
cuerpo_invalido400The body is not valid JSON.
texto_demasiado_largo400The text exceeds the character limit.
lote_invalido400A batch takes 2 to 100 items.
dialogo_invalido400A dialogue takes 2 to 100 turns and up to 5 voices.
webhook_invalido400webhook_url is not https or not a public host.
voz_sin_muestra400That voice can't be used yet.
texto_ilegible422The 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_disponible422That 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_insuficiente402Not enough credits (the response says how many are needed and includes buy_credits_url to get more).
requiere_compra403Batches and videos need an account that has bought credits.
voz_no_encontrada404The voice is not in your library.
biblioteca_llena409You already have the maximum number of saved voices: remove one in the web app to add another from the library.
no_encontrado404No job with that id (or it isn't yours).
marcas_no_disponibles404That audio has no timestamps: it hasn't finished yet or they aren't available for it.
limite_peticiones429Too many requests: wait for Retry-After.
demasiados_en_cola429Too many jobs in progress: wait for some to finish.
mantenimiento503Maintenance pause: retry later.
servicio_no_disponible503Service 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.