API-Referenz

Basis-URL https://api.vocallab.ai. Jede Anfrage benötigt Authorization: Bearer vl_live_... (siehe API-Schlüssel).

GET /api/v1/ping

Verbindungs- und Authentifizierungstest. Gibt dein Credit-Guthaben zurück.

{ "ok": true, "points": 12345, "unit": "points (1 pt ≈ 1 second of audio)" }

GET /api/v1/voices

Die Stimmen, die du nutzen kannst — zuerst deine geklonten und gestalteten Stimmen, dann der öffentliche Katalog. Verwende die zurückgegebene id als voice beim Generieren. Katalogstimmen akzeptieren auch ihren slug.

Jede Antwort enthält total, count, offset und has_more, du kannst also blättern, ohne zu raten. Dieselben vier Parameter (ohne type) funktionieren bei GET /api/v1/voices/clones und GET /api/v1/voices/designs.

curl "https://api.vocallab.ai/api/v1/voices?q=narrator&limit=20" \
  -H "Authorization: Bearer vl_live_..."

{ "voices": [
  { "id": "Ashley", "slug": "warm-natural-female-explainer-voice-for-youtube-podcasts",
    "name": "Warm Natural Female Explainer Voice for YouTube & Podcasts",
    "type": "preset", "languages": ["en"], "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en"] }
] }

GET /api/v1/models

Die auswählbaren Sprachmodelle. Übergib einen key als model an POST /api/v1/tts (Standard v-pro). API-Schlüssel können sie alle verwenden. Die Unterschiede findest du unter Sprachmodelle.

{ "default": "v-pro", "models": [
  { "key": "v-studio", "label": "VocalLab Studio",       "steerable": true,  "costMultiplier": 1,
    "supportsTemperature": false, "supportsDeliveryMode": true },
  { "key": "v-flash",  "label": "VocalLab Studio Flash", "steerable": false, "costMultiplier": 0.75,
    "supportsTemperature": false, "supportsDeliveryMode": false },
  { "key": "v-pro",    "label": "VocalLab Pro",          "steerable": false, "costMultiplier": 1,
    "supportsTemperature": true,  "supportsDeliveryMode": false },
  { "key": "v-lite",   "label": "VocalLab Lite",         "steerable": false, "costMultiplier": 0.5,
    "supportsTemperature": true,  "supportsDeliveryMode": false }
] }

POST /api/v1/tts

Sprache erzeugen.

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from VocalLab","voice":"Ashley"}'

Gibt das Audio inline (base64) plus eine id zurück. Die gehostete URL erscheint, sobald der Upload abgeschlossen ist — frage sie über GET /api/v1/tts/:id ab.

Jede Anfrage ist auf 2.000 Zeichen begrenzt und entspricht genau einer Sprachsynthese — es gibt kein verstecktes Aufteilen oder Fan-out, daher bleiben Kosten und Latenz pro Aufruf vorhersehbar. Anfragen werden gegen dein Punkteguthaben abgerechnet und laufen durch eine Fair-Use-Warteschlange, sodass intensive Automatisierung nie die App blockiert. Um ein längeres Skript zu vertonen, teile es in Stücke von höchstens 2.000 Zeichen und sende sie als separate Aufrufe (unter Beachtung des Ratenlimits von 60 Anfragen/Minute bzw. 120 im Max-Tarif).

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions",
  "format": "MP3", "model": "v-pro", "points_used": 12 }

Modell & Kosten. v-flash berechnet ¾ (points = ⌈ Zeichen ÷ 20 ⌉) und v-lite die Hälfte (÷ 30) der Punkte von v-pro/v-studio (÷ 15). v-studio ist das einzige Modell, das Ausdrucks-/Steuerungsanweisungen befolgt — siehe Sprachmodelle und Voice Steering.

Pausen

Eine Stille exakter Länge fügst du mit einem selbstschließenden <break />-Tag direkt im text ein:

{ "text": "Lass mich überlegen <break time=\"1.5s\" /> Ja, ich habe darüber nachgedacht.", "voice": "Ashley" }

• Sekunden oder Millisekunden — 1.5s = 1500ms.
• Bis zu 20 Break-Tags pro Anfrage, in jeder unterstützten Sprache.
• Break-Tags zählen zum 2.000-Zeichen-Limit und werden aus Untertiteln/SRT entfernt.

GET /api/v1/tts/:id

Generierungsstatus und die gehostete Audio-URL, sobald sie bereit ist.

{ "id": "...", "status": "ready", "audio_url": "https://...",
  "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions", "format": "MP3" }

GET /api/v1/tts/:id/audio

Streame die Audiobytes des fertigen Clips direkt — eine Alternative zum base64-Blob audio_base64. Wird inline ausgeliefert (spielt im Browser oder Media-Player ab) und unterstützt den HTTP-Range-Header, sodass Clients spulen können. Solange der Clip noch fertiggestellt wird, kommt 409 — frage GET /api/v1/tts/:id ab, bis status ready ist, und streame dann.

curl -L https://api.vocallab.ai/api/v1/tts/GENERATION_ID/audio \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.mp3

Derselbe Link wird als stream_url bei POST /api/v1/tts und GET /api/v1/tts/:id zurückgegeben.

GET /api/v1/tts/:id/captions

Untertitel einer Generierung als .srt-Datei. Die Cues folgen dem tatsächlichen Sprechtempo (Wort-Timings aus der Synthese), und jegliche [emotion]-Markierung oder <break />-Pause wird entfernt — nur gesprochene Wörter landen in der Datei.

Untertitel werden aus den gespeicherten Timings gebaut, nicht aus der Audiodatei — sie sind sofort verfügbar, auch während status noch pending ist.

curl -L "https://api.vocallab.ai/api/v1/tts/GENERATION_ID/captions" \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.srt

1
00:00:00,000 --> 00:00:01,240
Hello from VocalLab,

2
00:00:01,240 --> 00:00:03,100
this is your narrator speaking.

Mit format=json:

{ "id": "...", "mode": "phrase", "duration": 3.1,
  "srt": "1\n00:00:00,000 --> 00:00:01,240\nHello from VocalLab,\n\n...",
  "words": [ { "word": "Hello", "start": 0, "end": 0.32 } ] }

Derselbe Link wird als captions_url bei POST /api/v1/tts und GET /api/v1/tts/:id zurückgegeben. Mit "captions": true bei POST /api/v1/tts kommt das SRT direkt zusammen mit dem Audio zurück.

Gibt 409 captions_unavailable zurück, wenn zu einer Generierung keine Wort-Timings gespeichert sind (einige ältere Clips) — das Audio ist davon nicht betroffen.

DELETE /api/v1/tts/:id

Lösche eine dir gehörende Generierung endgültig — sowohl die gespeicherte Audiodatei als auch ihren Datenbankeintrag. Praktisch zum Aufräumen nach dem Download oder zum Erfüllen einer Löschanfrage. Eine id, die nicht existiert oder nicht dir gehört, ergibt 404.

curl -X DELETE https://api.vocallab.ai/api/v1/tts/GENERATION_ID \
  -H "Authorization: Bearer vl_live_..."

{ "ok": true, "id": "...", "deleted": true }

GET /api/v1/voices/languages

Neu: GET /api/v1/voices/languages liefert jetzt über 470 Sprachen samt Akzentvarianten (z. B. en-GB, pt-PT). code ist ein BCP-47-Tag; die alten Enum-Werte (EN_US, PT_BR, …) und Other werden weiterhin akzeptiert.

Die Sprachen und Aufnahmegrenzen für Cloning und Voice Design. Frag sie hier ab, statt die Liste fest zu verdrahten — es ist dieselbe Quelle, die auch das Upload-Formular im Studio liest.

{ "languages": [
    { "name": "English", "code": "EN_US", "experimental": false },
    { "name": "Other",   "code": "AUTO",  "experimental": true }
  ],
  "sample_limits": { "max_samples": 1, "max_base64_length": 4194304,
                     "allowed_formats": ["mp3", "wav", "webm"] } }

Voice Design

Erfinde eine völlig neue Stimme aus einer schriftlichen Beschreibung — ganz ohne Aufnahme. Es sind zwei Aufrufe: Kandidaten-Vorschauen erzeugen, dann die beste behalten.

POST /api/v1/voices/designs/previews

Erzeugt bis zu drei Stimmkandidaten. Kostet Points — jede Vorschau ist eine echte Synthese von preview_text zum API-Tarif (⌈Zeichen ÷ 15⌉ pro Vorschau).

Gespeichert wird noch nichts, also belegt das keinen Design-Platz — aber es setzt einen freien voraus. Sind deine Designs bereits am Tariflimit, antwortet der Aufruf mit 409 design_limit und es werden keine Points abgebucht: für eine Stimme, die du nicht behalten kannst, sollst du nicht zahlen.

curl -X POST https://api.vocallab.ai/api/v1/voices/designs/previews \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A warm, unhurried British woman in her forties, low and reassuring, like a documentary narrator.","count":2}'

{ "previews": [
    { "preview_id": "...", "text": "Hello! This is a preview of my voice...",
      "preview_url": "https://api.vocallab.ai/api/v1/audio/..." }
  ],
  "points_used": 12, "expires_in": 1800 }

Eine preview_id ist noch keine nutzbare Stimme und rund 30 Minuten gültig.

Vorschauen, die du nicht behältst, werden verworfen. Speichere die gewünschte, bevor du einen neuen Satz erzeugst — ein erneuter Aufruf verwirft deine vorherigen Vorschauen und ihre preview_urls hören auf zu funktionieren, und das Speichern einer verwirft den Rest ihres Satzes. In beiden Fällen bleibt nichts zurück.

POST /api/v1/voices/designs

Behält eine Vorschau als dauerhafte Stimme. Kostet keine Points (die Vorschauen wurden bereits berechnet), belegt aber einen Design-Platz deines Tarifs. Die zurückgegebene id funktioniert sofort als voice in POST /api/v1/tts.

{ "id": "default-abc123__narrator", "name": "Documentary Narrator", "type": "designed",
  "languages": ["EN_US"], "created_at": "...",
  "preview_url": "https://api.vocallab.ai/api/v1/audio/...", "used": 3, "limit": 20 }

GET /api/v1/voices/designs

Deine gestalteten Stimmen, neueste zuerst, mit Platznutzung: { "voices": [...], "used": 3, "limit": 20 }.

DELETE /api/v1/voices/designs/:voiceId

Löscht die Stimme beim Anbieter und aus deiner Bibliothek. In bezahlten Tarifen wird ein Platz frei. Antwortet mit { "ok": true, "id": "...", "deleted": true }.

Voice Cloning

Bilde eine bestimmte Stimme aus einer kurzen Aufnahme nach. Cloning kostet keine Points — begrenzt ist nur die Zahl der Clone-Plätze deines Tarifs. Klone ausschließlich Stimmen, die dir gehören oder für die du eine schriftliche Erlaubnis hast.

POST /api/v1/voices/clones

Fast jede Audiodatei funktioniert. audio_base64 ist das rohe base64 deiner Aufnahme, ohne data:-Präfix — MP3, WAV, M4A, AAC, OGG, FLAC, WebM, die Tonspur eines MP4 und mehr. Alles, was der Sprachanbieter nicht direkt annimmt, wird serverseitig in mono 16-Bit-WAV konvertiert, genau wie es die Web-Apps vor dem Upload im Browser tun — die API ist also nicht wählerischer als das Studio.

• kürzt auf die ersten 30 Sekunden — eine längere Datei darf gesendet werden, genutzt wird nur der Anfang;
• mischt Stereo auf Mono und rechnet auf 32 kHz um;
• verkleinert übergroße Dateien, ein großes 24-Bit-Studio-WAV muss also nicht mehr von Hand vorbereitet werden.

Die Grenze gilt für den base64-String, nicht für die dekodierten Bytes: bis zu 8.000.000 Zeichen, rund 6 MB Datei. Darüber kommt 413 sample_too_large; eine Datei ohne lesbares Audio ergibt 400 unreadable_audio.

Wurde etwas verändert, enthält die Antwort ein audio_notes-Array, das das benennt — lohnt sich zu loggen, damit ein Klon aus den ersten 30 Sekunden einer langen Aufnahme nie eine stille Überraschung ist:

{ "id": "...", "name": "My Narrator", "type": "clone", "used": 2, "limit": 100,
  "audio_notes": ["Re-encoded to mono 16-bit WAV at 32 kHz — aac isn't a format the provider accepts.",
                  "Trimmed to the first 30s (the sample was 90s)."] }

curl -X POST https://api.vocallab.ai/api/v1/voices/clones \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"My Narrator\",\"language\":\"English\",\"samples\":[{\"audio_base64\":\"$(base64 -w0 sample.mp3)\"}]}"

{ "id": "default-abc123__my-narrator", "name": "My Narrator", "type": "clone",
  "languages": ["EN_US"], "created_at": "...", "used": 2, "limit": 100 }

GET /api/v1/voices/clones

Deine geklonten Stimmen, neueste zuerst, mit Platznutzung: { "voices": [...], "used": 2, "limit": 100 }.

DELETE /api/v1/voices/clones/:voiceId

Löscht die Stimme beim Anbieter und aus deiner Bibliothek. In bezahlten Tarifen wird ein Platz frei. Antwortet mit { "ok": true, "id": "...", "deleted": true }.

Plätze sind getrennt. Geklonte und gestaltete Stimmen teilen sich nie ein Budget — die Zahlen je Tarif stehen unter Tarife & Limits. Im Free-Tarif gilt das Limit lebenslang: Löschen gibt den Platz nicht frei. In einem Workspace arbeiten Mitglieder innerhalb der Limits des Inhabers, und Design-Points gehen vom Guthaben des Inhabers ab.

Was Points kostet

GET /api/v1/me

Dein Credit-Guthaben und dein Plan.

Fehler

Fehler haben die Form { "error": { "code": "...", "message": "..." } }.

Preise

Generierungen werden von deinem Punkteguthaben abgerechnet, berechnet aus der Textlänge (nicht aus der endgültigen Audiodauer):

points = ⌈ characters ÷ 15 ⌉      (API-Rate — etwa 15 Zeichen pro Punkt)

⌈ ⌉ rundet auf den nächsten ganzen Punkt auf. Die Web-App rechnet mit 17 Zeichen pro Punkt, die API hat also einen kleinen Aufschlag (~13 %). Punkte werden vor dem Aufruf beim Sprachanbieter abgerechnet — eine Anfrage, die dein Guthaben übersteigen würde, liefert 402 und wird nie generiert. Jede Antwort enthält die genauen points_used. Da gesprochene Sprache im Schnitt ~15–17 Zeichen/Sekunde hat, gilt 1 Punkt ≈ 1 Sekunde Audio, die genaue Abbuchung folgt aber immer der obigen Formel. Mehr dazu unter Guthaben & Minuten.