Tasks
Check the status and results of synthesis tasks.
Text-to-speech and voice conversion both create "synthesis" tasks. Use these endpoints to check their status and get the audio.
The task object
{
"id": "9a3e6b1c-…",
"object": "synthesis",
"type": "tts",
"status": "completed",
"voice_id": "VOICE_ID",
"title": "Article 88, paragraph 1",
"text": "The weather is lovely today - perfect for a walk.",
"language": "en",
"speed": 1.1,
"mode": "balance",
"input_duration_seconds": null,
"audio_url": "https://cdn.voiceailabs.com/…/9a3e6b1c.mp3",
"duration_ms": 3240,
"credits_used": 17,
"batch_id": null,
"error": null,
"refund": null,
"created_at": "2026-10-09T02:00:00.000Z",
"updated_at": "2026-10-09T02:00:06.000Z"
}| Field | Description |
|---|---|
type | tts for text-to-speech, voice_conversion for voice conversion |
status | pending, processing, completed, failed |
audio_url | MP3 URL, only set when completed |
duration_ms | Length of the generated audio in milliseconds |
credits_used | Credits charged for the task |
batch_id | Batch ID if created through the batch endpoint |
error | On failure: { code, message, retryable } |
refund | On failure: { status, credits }, where status is refunded, pending (refund in progress) or none (nothing was charged) |
Get a task
GET /api/v1/syntheses/{id}Fetching an unfinished task also moves it forward. Polling tips:
- Poll every 2–5 seconds. A single text-to-speech task usually finishes within seconds to tens of seconds.
- If a task hasn't finished after 10 minutes, stop polling and contact support with the task
id. - Every poll counts toward your rate limit - use webhooks for large volumes.
List tasks
GET /api/v1/syntheses?page=1&limit=20&status=completed&type=tts| Parameter | Description |
|---|---|
page / limit | Pagination, limit 1–100, default 20 |
status | Only processing, completed or failed tasks |
type | tts or voice_conversion |
Newest first, including tasks created in the web app. Each item is a compact task object (id, type, status, voice_id, title, text, audio_url, credits_used, created_at).
Audio retention
Generated audio is kept for your plan's history retention period (Free 7 days, Starter 30 days, Standard 180 days, Premium 365 days). After that, audio_url stops working. Download the audio to your own storage once it's ready.