Fetch Bulk Text-to-Speech Results
Retrieves the results of multiple Text-to-Speech runs using a list of run_id values in a single request.
POST
Fetch Text-to-Speech Results
Bulk retrieval only helps when you already have run IDs from the deprecated async
POST /tts workflow. For anything new, stream each piece of speech with POST /tts-stream (split longer copy into segments if needed) instead of batching legacy runs.run_id, you can efficiently gather all your generated audio files in a single API call.
How to Use this Endpoint
Retrieving multiple generated audio files is straightforward - make aPOST request to this endpoint with an array of run_id values in the request body. The system will process all your completed tasks and return URLs for each audio file, making it easy to download or reference them in your application.
Understanding the Response
This endpoint returns a JSON response containing file URLs for each successfully processed run_id. Each audio file URL in the response corresponds to a completed text-to-speech task, allowing you to efficiently handle multiple audio files without the overhead of individual requests. The bulk response structure provides:- Organized Results: Each
run_idis mapped to its corresponding audio file URL. - Error Handling: Clear indication of any failed or unavailable runs.
- Efficient Processing: Single request handles multiple audio files.
Request Format
The request body should contain an array ofrun_id values for the completed text-to-speech tasks you want to retrieve:
Response Structure
The response will be a JSON object containing URLs for each successfully processed audio file:File URLs have an expiration time, so download or use them promptly rather than storing them long-term. Plan to process your audio files within a reasonable timeframe after retrieval.
Examples
Retrieving Multiple Audio Files
Here’s how to retrieve multiple generated audio files using Python:Best Practices
Request Size Requirements
This endpoint requires a specific batch size for optimal performance and resource management:- Minimum: You must provide at least 2
run_idvalues per request - Maximum: You can provide up to 5
run_idvalues per request - Validation: Requests outside this range will be rejected with a validation error
Handling Larger Datasets
If you have more than 5 completed TTS tasks to retrieve:- Split into Multiple Requests: Divide your
run_idlist into chunks of 2-5 items - Sequential Processing: Process chunks sequentially to avoid rate limiting
- Batch Management: Implement logic to group your run_ids efficiently
Next Steps
With your bulk audio retrieval capabilities in place, you can:- Build Efficient Workflows: Process multiple audio files simultaneously in your applications
- Create Batch Processing Systems: Handle large-scale content generation with minimal API overhead
- Implement Robust Error Handling: Ensure your application gracefully handles partial failures
- Optimize Resource Usage: Reduce API calls and improve application performance
Authorizations
Body
application/json
Last modified on May 14, 2026