Riferimento API

URL di base https://api.vocallab.ai. Ogni richiesta richiede Authorization: Bearer vl_live_... (vedi Chiavi API).

GET /api/v1/ping

Test di connessione + autenticazione. Restituisce il saldo dei tuoi punti.

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

GET /api/v1/voices

Le voci che puoi usare — il catalogo pubblico più le tue voci clonate e progettate. Usa un id restituito come voice per la generazione. Le voci del catalogo accettano anche il loro 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

I modelli vocali selezionabili. Passa una key come model in POST /api/v1/tts (predefinito v-pro). Le chiavi API possono usare tutti e tre. Vedi Modelli vocali per le differenze.

{ "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

Genera audio vocale.

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"}'

Restituisce l'audio inline (base64) più un id. L'URL ospitato compare una volta completato il caricamento — interrogalo con GET /api/v1/tts/:id.

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

Modello e costo. v-lite viene fatturato a metà dei punti di v-pro/v-studio (points = ⌈ caratteri ÷ 30 ⌉ invece di ÷ 15). v-studio è l'unico modello che segue le istruzioni di espressione/orientamento — vedi Modelli vocali e Orientamento vocale.

Pause

Inserisci un silenzio di durata esatta con un tag <break /> auto-chiudente direttamente in text:

{ "text": "Fammi pensare <break time=\"1.5s\" /> Sì, ci ho pensato.", "voice": "Ashley" }

• Secondi o millisecondi — 1.5s = 1500ms.
• Fino a 20 tag break per richiesta, in tutte le lingue supportate.
• I tag break contano nel limite di 2.000 caratteri e vengono rimossi da sottotitoli/SRT.

GET /api/v1/tts/:id

Stato della generazione e URL dell'audio ospitato una volta pronto.

{ "id": "...", "status": "ready", "audio_url": "https://...", "format": "MP3" }

GET /api/v1/me

Il saldo dei tuoi punti e il tuo piano.

Errori

Gli errori hanno la forma { "error": { "code": "...", "message": "..." } }.