Text-to-Speech-API: deine Stimmen direkt aus deinem Code
Eine einfache REST-API: Du schickst einen Text und eine deiner Stimmen und bekommst das MP3 zurück. Es gelten dieselben Credits wie auf der Website, ohne Entwicklergebühr und ohne Kosten pro Aufruf.
- Basis-URL
- https://voizum.com/api/v1
- Videos (v3)
- https://voizum.com/api/v3
- Authentifizierung
- Bearer sk_voizum_…
- Ausgabe
- MP3 · MP4
- Sprachen
- es · en · de · fr · pt · it · ru · nl · pl · zh · ja · ko · hi · ar · tr · id · ro
- Preis
- 60 Credits / 1.000 Zeichen (min. 100)
Für KI-Assistenten und Tools
Drei Wege, je nachdem, wer sich verbindet. Alle führen zum Gleichen: deine Stimmen und deine Credits.
- Claude, ChatGPT, Cursor… ohne Programmieren
- Der MCP-Connector: Füge ihn dem Assistenten hinzu und fordere Audio im Chat an.
- https://voizum.com/mcp
- ChatGPT Actions, Postman, Client-Generatoren
- Importiere die OpenAPI-3.1-Spezifikation: Sie beschreibt alle Endpunkte und ihre Felder.
- https://voizum.com/openapi.json
- Agenten, die Dokumentation lesen
- llms.txt: der ganze Vertrag als Klartext, gemacht für Sprachmodelle.
- https://voizum.com/llms.txt
In drei Schritten starten
- Erstelle dein Konto und deinen Schlüssel im API-Bereich der Website. Der Schlüssel beginnt mit sk_voizum_ und wird nur einmal angezeigt: Halte ihn geheim und bau ihn nie in Browser-Code ein.
- Wähle eine Stimme: Klone deine eigene oder füge eine aus der Stimmbibliothek zu „Meine Stimmen“ hinzu. GET /voices liefert ihre ID.
- Erstelle das Audio mit POST /tts, frage den Status alle paar Sekunden ab und lade es herunter, sobald es fertig ist (oder erhalte einen Webhook).
Ein vollständiges Beispiel
Erstellen, warten, herunterladen. Die API arbeitet asynchron: Ein langes Audio braucht Zeit, und so muss keine Verbindung offen bleiben.
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()));
}Endpunkte
| Methode und Pfad | Was es macht |
|---|---|
| GET /status | Status des Dienstes. Ohne Schlüssel. |
| GET /account | Dein Credit-Guthaben und der Preis pro Zeichen. |
| GET /voices | Die Stimmen deiner Bibliothek: Ihre ID ist die voice_id. |
| GET /library | Durchsucht die öffentliche Bibliothek (Filter: query, language, gender, age, style, accent, limit, offset). Jede Stimme nennt ihre source: voizum oder community. |
| POST /library/{voice_id} | Speichert eine öffentliche Stimme in deiner Bibliothek (kostenlos) und liefert DEINE voice_id für POST /tts. 201 bei neu, 200 wenn du sie schon hattest; 409 biblioteca_llena. |
| POST /tts | Erstellt ein Audio aus einem Text. |
| GET /tts/{job_id} | Status des Audios: queued, processing, done, error oder canceled. |
| GET /tts/{job_id}/audio | Das fertige MP3 (leitet auf die Datei weiter; ?download=1 zum Herunterladen). |
| GET /tts/{job_id}/timestamps | Wann jeder Satz und jedes Wort im MP3 zu hören ist, in Sekunden. Ohne Aufpreis. |
| GET /tts/{job_id}/subtitles | Fertige Untertitel: ?format=srt (Standard) oder vtt; ?download=1 zum Herunterladen. |
| DELETE /tts/{job_id} | Bricht ein Audio ab, das noch nicht begonnen hat: Die Credits werden zurückerstattet. |
| GET /tts | Deine letzten Audios, seitenweise. |
| POST /tts/batch | Mehrere getrennte Audios in einer Anfrage, mit nur einem Mindestpreis (2 bis 100). |
| POST /tts/dialogue | Ein Audio mit mehreren Stimmen im Wechsel (bis zu 5 Stimmen). |
Avatar-Videos (API v3)
Einer deiner Avatare sagt, was du willst, als MP4 im Querformat (16:9) oder Hochformat (9:16). Dafür gibt es eine eigene Basis-URL mit demselben Schlüssel im Header X-Api-Key. Antworten kommen in { "data": … }.
- Bereite den Avatar und seine Szenen auf der Website vor oder lade sie mit POST /avatars hoch. GET /avatars liefert die id jedes Avatars.
- Fordere das Video mit POST /videos an, oder mehrere auf einmal mit POST /videos/batches.
- Warte: Frage GET /videos/{id} alle paar Sekunden ab, GET /videos/statuses für mehrere, oder schick eine callback_url, dann melden wir uns. Ein Video dauert ein paar Minuten.
- Steht status auf completed, lade das MP4 über video_url herunter (mit deinem Schlüssel).
Ein Video von Anfang bis Ende
# 1. Deine Avatare und ihre Szenen (id und scene)
curl https://voizum.com/api/v3/avatars -H "X-Api-Key: $VOIZUM_API_KEY"
# 2. Video anfordern
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": "Hallo, ich bin dein Avatar.", "voice_id": "VOICE_ID", "aspect_ratio": "9:16"}'
# → {"data": {"id": "VIDEO_ID", "status": "pending", "credits": …, …}}
# 3. Status abfragen (bis "completed"; dauert ein paar Minuten)
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. MP4 herunterladen
curl -L -o video.mp4 https://voizum.com/api/v3/videos/VIDEO_ID/video -H "X-Api-Key: $VOIZUM_API_KEY"Avatare und Szenen
Ein Avatar ist eine Person. Seine Szenen sind Fotos derselben Person (anderer Ausschnitt, andere Kleidung, anderer Ort), nummeriert 1, 2, 3… Szene 1 ist die Hauptszene, und die Nummern ändern sich nicht, wenn du eine löschst.
Ein Video wählt avatar_id und scene (ohne scene die 1). Du kannst auch die id einer Szene als avatar_id schicken, dann ohne scene.
Um ein Foto mit POST /avatars hochzuladen, schick "consent": true: Es ist dein Gesicht oder du hast die Erlaubnis dieser Person. Ohne avatar_id entsteht ein neuer Avatar (mit name, Pflicht: bis zu 40 Zeichen und anders als deine anderen Avatare), mit avatar_id die nächste Szene. Bis zu 15 Avatare und 10 Szenen pro Avatar.
Avatare aus der Voizum-Bibliothek speicherst du auf der Website als Favoriten; in GET /avatars haben sie eine einzige Szene.
Was gesagt wird: drei Wege
script + voice_id: der Text und eine deiner Stimmen (GET /voices). Zuerst entsteht die Stimme, dann das Video; das Audio ist im Preis enthalten.
audio_id: die job_id eines Audios, das du schon mit POST /tts (API v1) erstellt hast. So hörst du es vorher an, und berechnet wird nur das Video.
audio_url: dein eigenes Audio (mp3, wav, m4a, ogg oder webm) unter einer öffentlichen https-URL.
Was POST /videos akzeptiert
| Feld | Was es ist |
|---|---|
| avatar_id | Pflicht (außer mit segments). Einer deiner Avatare (GET /avatars) oder die id einer Szene. |
| scene | Optional. Welche Szene des Avatars: standardmäßig die 1. |
| segments | Statt avatar_id: mehrere Teile (bis zu 20) in einem MP4, jeder mit seiner avatar_id, scene und dem, was gesagt wird. Siehe „Ein Video mit mehreren Teilen“. |
| script + voice_id | Was gesagt wird (bis zu 600.000 Zeichen) und mit welcher deiner Stimmen. Optional: voice_settings.speed, 0.5 bis 2. |
| audio_id | Statt script: die job_id eines fertigen Audios von dir (POST /tts der API v1). |
| audio_url | Statt script: dein eigenes Audio (mp3, wav, m4a, ogg oder webm) unter einer öffentlichen https-URL. |
| aspect_ratio | Optional. "16:9" (Standard) oder "9:16". |
| resolution | Optional. "1080p" (Standard, die beste Qualität) oder "720p" (schneller und günstiger, kann weniger scharf aussehen). |
| emotion | Optional. Das Gesicht: "smile" lächelt fast die ganze Zeit leicht; "serious", ernster, gefasster Ausdruck. Ohne: ruhig und natürlich. Gleicher Preis. |
| movement | Optional. Der Körper: "still" bewegt die Arme kaum; "expressive" gestikuliert mehr. Ohne: ab und zu eine natürliche Geste. Gleicher Preis. |
| callback_url | Optional. Eine öffentliche https-URL: Wir schicken einen POST, wenn das Video fertig ist. |
| callback_id | Optional. Deine eigene Referenz: Sie kommt im Video und in der Benachrichtigung zurück. |
| Idempotency-Key | Optionaler Header. Wiederholst du die Anfrage mit demselben, bekommst du dasselbe Video ohne erneute Abrechnung. |
Ein Video mit mehreren Teilen
Statt avatar_id schickst du segments: eine Liste von Teilen (bis zu 20), jeder Teil mit seinem Avatar, seiner Szene und dem Gesagten (avatar_id, scene und script + voice_id, audio_url oder audio_id). Sie werden der Reihe nach zu einem MP4 verbunden.
aspect_ratio, resolution, emotion, movement und callback_url stehen außerhalb der Liste und gelten für das ganze Video. Abgerechnet wird wie ein Video der Gesamtlänge, mit nur einem 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": "Hallo, ich bin Lucía.", "voice_id": "VOICE_ID"},
{"avatar_id": "AVATAR_ID", "scene": 3, "script": "Und das ist neu in diesem Monat.", "voice_id": "VOICE_ID"}
],
"aspect_ratio": "16:9",
"resolution": "1080p"
}'Mehrere Videos
Für mehrere schick sie zusammen mit POST /videos/batches: { "videos": [ … ] }, jedes mit denselben Feldern wie POST /videos. Das Minimum gilt einmal für alles, was du gleichzeitig anforderst: Kommen sie zusammen darüber, zahlt es keines. Schlägt eines fehl (Guthaben, Avatar…), kommt es mit seinem Fehler zurück, die anderen laufen weiter. Mit einem Idempotency-Key liefert derselbe Stapel dieselben Videos ohne erneute Abrechnung.
Deine Videos starten in der Reihenfolge ihres Eingangs und, wenn Platz ist, entstehen mehrere gleichzeitig; warten auch andere Kunden, wird der Platz unter allen aufgeteilt. Solange eines pending ist, kannst du es mit DELETE /videos/{id} abbrechen und bekommst die Credits zurück; ab processing nicht mehr.
Es gibt eine Obergrenze für gleichzeitig unfertige Videos: Überschreitest du sie, lautet die Antwort concurrency_limit – warte einfach, bis eines fertig ist.
Preis und Speicherung
resolution "1080p" (Standard, die beste Qualität): 3450 Credits pro Videominute. "720p" (schneller und günstiger, kann weniger scharf aussehen): 2000. Das hängt vom Avatar ab: am besten beide mit jedem Avatar testen.
Jedes Video kostet mindestens 1500 Credits; ist es länger als 26 s in 1080p oder 45 s in 720p, zahlt es nur seine Sekunden. Forderst du mehrere auf einmal an, gibt es ein Minimum für alle: Kommen sie zusammen darüber, wird es nicht berechnet. Bei script kommt das Audio zum normalen Preis dazu. Bis zu 35 Minuten pro Video, nur mit gekauften Credits.
POST /videos/estimate nennt dir die Kosten, ohne etwas zu erstellen. Abgerechnet wird bei der Anfrage; schlägt das Video fehl, wird alles erstattet. Bei script wird die Länge anhand der Zeichen geschätzt und nach Messung der echten Stimme angepasst.
Das MP4 wird 4 Tage gespeichert: Lade es herunter und speichere es selbst.
Callback
Mit callback_url schicken wir einen POST, wenn das Video fertig ist, erfolgreich oder nicht (3 Versuche, je 10 s Timeout). Das Wichtige steht in event_type und event_data; url lädt das MP4 mit deinem Schlüssel herunter.
Die Benachrichtigung ist nicht signiert: Nimm sie als Anlass, GET /videos/{id} mit deinem Schlüssel abzufragen, denn das ist die verlässliche Quelle.
{
"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-Endpunkte
| Methode und Pfad | Was es macht |
|---|---|
| GET /users/me | Prüft den Schlüssel: dein Guthaben, die Videopreise und deine Limits. |
| GET /voices | Die Stimmen deiner Bibliothek (ihre voice_id). |
| GET /avatars | Deine Avatare mit ihren Szenen und deine Favoriten aus der Bibliothek. |
| POST /avatars | Lädt ein Foto hoch: ein neuer Avatar oder eine weitere Szene (mit consent). |
| GET /avatars/{id} | Ein Avatar mit seinen Szenen. |
| PATCH /avatars/{id} | Benennt ihn um. |
| DELETE /avatars/{id} | Löscht ihn mit allen Szenen (fertige Videos bleiben). |
| DELETE /avatars/scenes/{id} | Löscht eine Szene; die anderen behalten ihre Nummer. |
| POST /videos | Erstellt ein Video. |
| POST /videos/batches | Mehrere Videos in einer Anfrage, mit einem Minimum für alle. |
| POST /videos/estimate | Wie viele Credits es kosten würde, ohne etwas zu erstellen oder abzurechnen. |
| GET /videos/{id} | Status: pending, processing, completed, failed oder canceled. |
| GET /videos/statuses?ids=a,b | Der Status von bis zu 100 Videos auf einmal. |
| GET /videos | Deine Videos, die neuesten zuerst (limit und token). |
| DELETE /videos/{id} | Bricht ein Video ab, das noch pending ist: Die Credits kommen zurück. |
| GET /videos/{id}/video | Das fertige MP4 (leitet zum Download weiter). |
Fehler bei Videos
In der Form { "error": { "code", "message", "param", "request_id" } }: param ist das fehlerhafte Feld (falls vorhanden), request_id kommt auch im Header X-Request-Id. Die Meldungen sind auf Englisch.
| Code | HTTP | Was passiert ist |
|---|---|---|
| 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. |
Du kommst von HeyGen?
Ändere die Basis-URL und den Schlüssel. Statt einer Look-ID schickst du avatar_id + scene (die id der Szene geht auch). resolution ist "1080p" oder "720p". Alles andere funktioniert gleich.
Was POST /tts akzeptiert
| Feld | Was es ist |
|---|---|
| text | Pflicht. Der Text, bis zu 600.000 Zeichen. |
| voice_id | Pflicht. Eine Stimme aus deiner Bibliothek (GET /voices). |
| speed | Optional. Geschwindigkeit, 0.5 bis 2 (1 = das natürliche Tempo der Stimme). |
| pause_ms | Wird akzeptiert, ändert mit Voizum 2 aber nichts: Die Pausen zwischen Sätzen setzt das Modell. Für eine bestimmte Pause schreibe <#1.5#> (Sekunden) in den Text. |
| <#…#> | Marken im Text, ohne Kosten: <#1.5#> ist eine Pause von 1,5 s, <#traurig#>, <#lachen#>, <#flustern#>… eine Emotion bis zum Absatzende oder bis <#normal#> (in es, en, pt, de und fr). |
| language | Optional. auto, es, en, de, fr, pt, it, ru, nl, pl, zh, ja, ko, hi, ar, tr, id, ro. Ohne Angabe wird die Sprache aus dem Text erkannt. |
| loudness_normalization | Optional. Gleicht die Lautstärke an, damit alle Stimmen gleich laut klingen. |
| tone | Optional, nur bei /tts. Der Ton des ganzen Audios (spanische Namen): tranquilo, suave, susurro, alegre, emocionado, triste, nostalgico, decidido, asustado. Für einen Abschnitt eine Emotions-Marke im Text. |
| webhook_url | Optional. Eine öffentliche https-URL, an die wir einen POST senden, wenn das Audio fertig ist. |
| Idempotency-Key | Optionaler Header. Wiederholst du die Anfrage mit demselben Wert, bekommst du dasselbe Audio und zahlst nicht doppelt. |
Webhook
Mit webhook_url musst du nicht abfragen: Sobald das Audio fertig ist, senden wir einen POST mit dem Ereignis generation.finished (3 Versuche, je 10 s Timeout). Antwortet dein Server mit einem 4xx, gibt es keinen neuen Versuch.
Die Benachrichtigung ist nicht signiert: Nimm sie als Anlass, GET /tts/{job_id} mit deinem Schlüssel abzufragen, denn das ist die verlässliche Quelle, und nicht als Beweis, dass das Audio fertig ist.
{
"event": "generation.finished",
"id": "JOB_ID",
"status": "completed",
"voice_id": "VOICE_ID",
"duration_seconds": 12.4,
"credits": 100,
"error": null
}Zeitmarken und Untertitel
Wenn ein Voizum-2-Audio auf done steht, liefert GET /tts/{job_id} timestamps_url und subtitles_url (Audios vor dem 17.11.2026 haben sie nicht). Die erste gibt jeden Satz (segments) und jedes Wort (words) mit Start und Ende in Sekunden des MP3, Geschwindigkeit schon eingerechnet; die zweite die Untertitel als SRT oder WebVTT, ein Satz pro Untertitel (geteilt, wenn er 2 Zeilen à 42 Zeichen oder 7 Sekunden überschreitet). Sie kosten nichts und bleiben so lange gespeichert wie der Job, auch wenn das MP3 vorher abläuft.
Die Wörter sind die gesprochenen: Zahlen, Daten und Symbole stehen so da, wie sie gesagt werden („1889“ → „achtzehnhundertneunundachtzig“), und die Marken (<#1.5#>, <#triste#>) fehlen. Satzzeichen hängen am Wort. Im Chinesischen und Japanischen ist jedes Zeichen ein Wort. Die Zeiten sind eine sehr genaue Schätzung: Die Hälfte der Wörter liegt weniger als 0,07 s daneben, der Anfang jedes Satzes nur wenige Hundertstel.
{
"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 Erstellungen pro Minute (POST /tts, /tts/batch und /tts/dialogue teilen sich dieses Limit) und insgesamt 300 Anfragen pro Minute und Schlüssel. Antworten beim Erstellen enthalten X-RateLimit-Limit und X-RateLimit-Remaining, und jede 429 enthält Retry-After mit den Sekunden, die du warten musst.
Das MP3 wird 4 Tage gespeichert; danach liefert GET /tts/{job_id}/audio ein 404, lade es also herunter und bewahre es selbst auf.
Ein Audio darf bis zu 600.000 Zeichen lang sein. Ein Stapel umfasst 2 bis 100 Audios und insgesamt 1.200.000 Zeichen. Ein Dialog hat bis zu 100 Beiträge und 5 verschiedene Stimmen.
Fehler
Immer dieselbe Form: { "error": { "code", "message" } }, manchmal mit Details (zum Beispiel, wie viele Credits fehlen). Die Meldungen sind auf Englisch.
| Code | HTTP | Was passiert ist |
|---|---|---|
| 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. |
Fragen
- Gibt es ein SDK für Python oder JavaScript?
- Du brauchst keins: Es sind ein paar REST-Aufrufe mit JSON, die mit jedem HTTP-Client funktionieren (requests, fetch, curl). Wenn du einen generierten Client möchtest, erzeugt ihn die OpenAPI-Spezifikation in deiner Sprache.
- Gibt es Streaming in Echtzeit?
- Nein. Die API arbeitet asynchron: Du erstellst das Audio, fragst den Status ab und lädst das fertige MP3 herunter. Sie ist für Erzählungen, Videos, Kurse und Inhalte gedacht, nicht für Live-Gespräche.
- Kann ich die Stimmen der Bibliothek nutzen?
- Ja, in zwei Schritten: Suche mit GET /library und speichere die passende mit POST /library/{voice_id} (oder füge sie auf der Website hinzu); du erhältst DEINE voice_id für POST /tts. Die API generiert nur mit deinen eigenen Stimmen. Mit source: community markierte Stimmen wurden von anderen Nutzern hochgeladen: Voizum prüft ihre Herkunft nicht und übernimmt dafür keine Verantwortung; Nutzung auf eigenes Risiko, bitte die Rechte der Person achten, der die Stimme gehört.
- Kann ich eine Stimme über die API klonen?
- Nein: Geklont wird auf der Website (du lädst die Aufnahme einmal hoch), danach nutzt du die Stimme über die API mit ihrer voice_id.
- Was kostet das?
- Dasselbe wie auf der Website: 60 Credits pro 1.000 Zeichen, mindestens 100 pro Anfrage. Keine Monatsgebühr und keine Kosten pro Aufruf. Schlägt ein Audio fehl, werden die Credits zurückerstattet.
- In welchem Format kommt das Audio?
- MP3.
- Kann ich mehrere Videos auf einmal anfordern?
- Ja, mit POST /videos/batches: ein Minimum für alle, und kommen sie zusammen darüber, zahlt es keines. Sie starten in Reihenfolge und, wenn Platz ist, mehrere gleichzeitig; die wartenden stehen auf pending und sind bis zum Start abbrechbar.
- Kann ich ein Foto über die API hochladen?
- Ja, mit POST /avatars und "consent": true – damit bestätigst du, dass es dein Gesicht ist oder du die Erlaubnis dieser Person hast. Du kannst es auch auf der Website hochladen.
- Welche Avatare kann ich nutzen?
- Deine eigenen und die Bibliotheks-Avatare in deinen Favoriten. GET /avatars listet sie alle mit ihren Szenen.
Gib deinen Text ein und hör ihn mit einer echten Stimme
Die API verbraucht Credits aus einem Paket (60 pro 1.000 Zeichen). Pakete ab 5,99 €, ohne Abo.