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

Stimmen, die du verwenden kannst — der öffentliche Katalog plus deine eigenen geklonten und designten Stimmen. Verwende eine zurückgegebene id als voice für die Generierung. Katalogstimmen akzeptieren auch ihren slug.

{ "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 alle drei verwenden. Die Unterschiede findest du unter Sprachmodelle.

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

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.

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "format": "MP3", "model": "v-pro", "points_used": 12 }

Modell & Kosten. v-lite berechnet die Hälfte der Punkte von v-pro/v-studio (points = ⌈ Zeichen ÷ 30 ⌉ statt ÷ 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://...", "format": "MP3" }

GET /api/v1/me

Dein Credit-Guthaben und dein Plan.

Fehler

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