Overview
Async Synthesis is designed for processing large volumes of text that exceed real-time streaming limits. It allows you to submit a synthesis task and retrieve the result once processing is complete, making it ideal for:- Full document or article narration
- Podcast generation
- Long-form storytelling
- Batch processing of notifications
The Async Lifecycle
Integrating Async Synthesis involves a simple sequence:1
Submit Task
Call
POST /api/tts/{voice_id}/async with your text. You will receive a unique task_id.2
Poll Status
Periodically check
GET /api/tts/tasks/{task_id} to monitor progress. We recommend polling every 2-5 seconds.3
Download Result
Once the status is
completed, call GET /api/tts/tasks/{task_id}/download to get your audio file.4
Optional: Cleanup
You can cancel an ongoing task using
DELETE /api/tts/tasks/{task_id} if it’s no longer needed.Interactive Playground
Test the async flow directly. This playground will return the JSON response from the task creation.Create Async Task
Submit your text for background processing.Get Task Status
Retrieve the current state and progress of a task.Task Statuses
| Status | Description |
|---|---|
pending | Task is in queue and waiting for a worker. |
processing | Task is currently being synthesized. |
completed | Synthesis is finished and ready for download. |
failed | Processing encountered an error. |
Download Task Result
Retrieve the final audio file for a completed task.This endpoint returns the binary audio file directly. Ensure your client handles binary streams and sets the correct file extension based on your requested
output_format.Cancel Task
If you no longer need the result of a task that ispending or processing, you can cancel it to free up your concurrency limit.
Limits & Recommendations
- Max Characters: Up to 100,000 characters per task.
- Expiration: Task results are typically available for download for 24 hours.
- Concurrency: Check your plan for maximum concurrent async tasks allowed.