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 — prima le tue voci clonate e progettate, poi il catalogo pubblico. Usa l'id restituito come voice in generazione. Le voci del catalogo accettano anche il loro slug.

Ogni risposta porta total, count, offset e has_more, così puoi paginare senza tirare a indovinare. Gli stessi quattro parametri (tranne type) funzionano su GET /api/v1/voices/clones e 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

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

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

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.

Ogni richiesta è limitata a 2.000 caratteri e corrisponde esattamente a una sintesi vocale: non c'è alcuna suddivisione o moltiplicazione nascosta, quindi costo e latenza di ogni chiamata restano prevedibili. Le richieste vengono conteggiate sul tuo saldo di punti e passano da una coda di uso equo, così l'automazione intensiva non blocca mai l'app. Per narrare uno script più lungo, suddividilo in pezzi da ≤ 2.000 caratteri e inviali come chiamate separate (rispettando il limite di 60 richieste/minuto, o 120 con Max).

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

Modello e costo. v-flash viene fatturato a ¾ (points = ⌈ caratteri ÷ 20 ⌉) e v-lite a metà (÷ 30) dei punti di v-pro/v-studio (÷ 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://...",
  "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

Trasmetti in streaming direttamente i byte audio del clip finito — un'alternativa al blob base64 audio_base64. Servito inline (si riproduce in un browser o lettore multimediale) e supporta l'header HTTP Range per consentire lo scorrimento. Restituisce 409 mentre il clip è ancora in fase di finalizzazione: interroga GET /api/v1/tts/:id finché status non è ready, poi trasmetti.

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

Lo stesso link viene restituito come stream_url in POST /api/v1/tts e GET /api/v1/tts/:id.

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

I sottotitoli di una generazione, come file .srt. I cue seguono il parlato reale (timing per parola restituiti con la sintesi) e ogni markup [emotion] o pausa <break /> viene rimosso, così nel file finiscono solo le parole pronunciate.

I sottotitoli vengono costruiti dai timing salvati, non dal file audio: sono disponibili subito, anche mentre status è ancora pending.

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.

Con 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 } ] }

Lo stesso link viene restituito come captions_url in POST /api/v1/tts e GET /api/v1/tts/:id. Per ricevere l'SRT insieme all'audio in una sola chiamata, invia "captions": true su POST /api/v1/tts.

Restituisce 409 captions_unavailable quando una generazione non ha timing delle parole salvati (qualche clip più vecchio) — l'audio non è interessato.

DELETE /api/v1/tts/:id

Elimina definitivamente una generazione di tua proprietà — sia il file audio memorizzato sia il suo record nel database. Utile per fare pulizia dopo un download o per soddisfare una richiesta di cancellazione dei dati. Un id che non esiste, o che non è tuo, restituisce 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

Novità: GET /api/v1/voices/languages restituisce ora oltre 470 lingue con le relative varianti di accento (per esempio en-GB, pt-PT). code è un tag BCP-47; i vecchi valori (EN_US, PT_BR, …) e Other continuano a essere accettati.

Le lingue e i limiti di registrazione validi per clonazione e voice design. Interroga questo endpoint invece di scrivere la lista nel codice: è la stessa fonte di verità usata dal modulo di caricamento dello Studio.

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

Inventa una voce del tutto nuova partendo da una descrizione scritta, senza registrare nulla. Sono due chiamate: generare le anteprime candidate e salvare quella che preferisci.

POST /api/v1/voices/designs/previews

Genera fino a tre voci candidate. Addebitato in points — ogni anteprima è una sintesi reale di preview_text alla tariffa API (⌈caratteri ÷ 15⌉ per anteprima).

Non viene ancora salvato nulla, quindi la chiamata non occupa un posto di design — ma ne richiede uno libero. Se i tuoi design sono già al limite del piano la chiamata risponde 409 design_limit e non viene speso alcun point: pagare per una voce che non potresti conservare non avrebbe senso.

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 }

Un preview_id non è ancora una voce utilizzabile ed è valido per circa 30 minuti.

Le anteprime che non conservi vengono eliminate. Salva quella che vuoi prima di generarne altre: richiamare questo endpoint elimina le anteprime precedenti e i loro preview_url smettono di funzionare, e salvarne una elimina il resto del lotto. In entrambi i casi non resta nulla.

POST /api/v1/voices/designs

Conserva un'anteprima come voce permanente. Non costa points (le anteprime sono già state addebitate) ma occupa uno dei posti di design del tuo piano. L'id restituito funziona subito come 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

Le tue voci progettate, dalla più recente, con l'uso dei posti: { "voices": [...], "used": 3, "limit": 20 }.

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

Elimina la voce dal provider e dalla tua libreria. Su un piano a pagamento libera un posto. Restituisce { "ok": true, "id": "...", "deleted": true }.

Clonazione vocale

Ricrea una voce specifica da una breve registrazione. Clonare non costa points: è limitato solo dal numero di posti di clonazione del tuo piano. Clona esclusivamente voci di tua proprietà o per cui hai un permesso scritto.

POST /api/v1/voices/clones

Va bene quasi qualsiasi file audio. audio_base64 è il base64 puro della tua registrazione, senza prefisso data: — MP3, WAV, M4A, AAC, OGG, FLAC, WebM, la traccia audio di un MP4 e altro. Tutto ciò che il provider vocale non accetterebbe direttamente viene convertito lato server in WAV mono a 16 bit, esattamente come fanno le app web nel browser prima di caricare: l'API non è più esigente dello Studio.

• taglia ai primi 30 secondi — puoi inviare un file più lungo, ma viene usato solo l'inizio;
• converte lo stereo in mono e ricampiona a 32 kHz;
• riduce i file troppo grandi, così un WAV da studio a 24 bit non va più preparato a mano.

Il limite riguarda la stringa base64, non i byte decodificati: fino a 8.000.000 di caratteri, circa un file da 6 MB. Oltre, la chiamata risponde 413 sample_too_large; un file senza audio leggibile risponde 400 unreadable_audio.

Quando qualcosa è stato modificato, la risposta include un array audio_notes che lo dichiara — vale la pena registrarlo, così un clone costruito sui primi 30 secondi di una lunga registrazione non è mai una sorpresa silenziosa:

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

Le tue voci clonate, dalla più recente, con l'uso dei posti: { "voices": [...], "used": 2, "limit": 100 }.

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

Elimina la voce dal provider e dalla tua libreria. Su un piano a pagamento libera un posto. Restituisce { "ok": true, "id": "...", "deleted": true }.

I posti sono separati. Voci clonate e progettate non condividono mai un budget — vedi Piani e limiti per i numeri di ciascun piano. Nel piano Free il tetto è a vita: eliminare una voce non libera il posto. In uno spazio di lavoro i membri operano entro i limiti del piano del proprietario, e i points del design escono dal saldo del proprietario.

Cosa costa points

GET /api/v1/me

Il saldo dei tuoi punti e il tuo piano.

Errori

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