Fetch Text to Sound Run Results (Bulk)

This endpoint retrieves audio outputs generated from multiple previously completed Text to Sound tasks in a single request. It allows you to efficiently fetch results for several text-to-sound generation runs simultaneously, making it ideal for batch processing workflows and applications that need to handle multiple audio files at once.

Unlike the single result endpoint that takes a run ID as a URL parameter, this bulk endpoint accepts multiple run IDs in the request body, providing a more efficient way to retrieve results when working with multiple text-to-sound tasks.

​

How It Works

The endpoint processes an array of run IDs and returns corresponding results for each completed task. This batch approach offers several advantages over making individual requests for each result:

Efficiency Benefits:

• Reduces the number of HTTP requests needed
• Minimizes network overhead when fetching multiple results
• Simplifies client-side code for handling multiple audio files
• Provides better performance for applications processing many audio generations

Practical Applications:

• Batch processing of multiple text-to-sound requests
• Building audio libraries from multiple text prompts
• Creating soundtracks or audio collections
• Processing results from parallel text-to-sound tasks

​

Request Format

The endpoint expects a JSON payload containing an array of run IDs that you want to retrieve results for:

// Note: Replace with your actual Run IDs
{
  "run_ids": [
    "12345",
    "678910",
    "112233"
  ]
}

Each run ID should correspond to a previously initiated and completed text-to-sound task. The endpoint will process all provided run IDs and return results for those that have completed successfully.

​

Response Structure

The response contains an array of results, where each item corresponds to one of the requested run IDs. Each result includes a presigned URL that points directly to the generated audio file:

[
    12345: {
      "output_url": "https://storage.example.com/audio/12345.wav"
    },
    678910: {
      "output_url": "https://storage.example.com/audio/678910.wav"
    },
    112233: {
      "output_url": "https://storage.example.com/audio/112233.wav"
    }
]

​

Example Usage

​

Basic Bulk Request

curl -X POST "https://client.camb.ai/apis/text-to-sound-results" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_ids": [
    "12345",
    "678910",
    "112233"
  ]
  }'

​

Processing the Response

// Example JavaScript code for handling the bulk response
const response = await fetch('/text-to-sound-results', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    run_ids: [
      "12345",
      "678910",
      "112233"
    ]
  })
});

const data = await response.json();

// Process each result
data.results.forEach(result => {
    console.log(`Audio ready for ${result}: ${result.output_url}`);
    // Download or process the audio file
});

​

Error Handling and Status Management

When working with bulk requests, it’s important to understand that individual tasks within your batch may have different statuses. The endpoint will return results for all requested run IDs, but some may not be ready yet or may have encountered errors.

Best Practices for Error Handling:

1. Always check the status field for each result before attempting to use the output URL
2. Handle failed tasks gracefully with appropriate user feedback
3. Store successful results promptly as URLs may expire

​

Workflow Integration

This bulk endpoint fits naturally into larger audio processing workflows. Consider this typical pattern:

1. Initiate Multiple Tasks: Submit several text-to-sound requests using the creation endpoint
2. Store Run IDs: Keep track of all returned run IDs from your requests
3. Process Completed Results: Download and handle audio files for completed tasks
4. Retry or Handle Failures: Manage any failed tasks or retry processing tasks

​

Technical Considerations

File Format and Quality: The generated audio files are delivered in WAV format, providing high audio quality suitable for professional applications. Keep in mind that WAV files are larger than compressed formats but offer the best fidelity for your generated sound effects.

URL Expiration: The presigned URLs returned in the response are temporary and will expire after a certain period. Make sure to download and store important audio files promptly to avoid losing access to your generated content.

Rate Limiting: While this endpoint allows bulk retrieval, be mindful of the fact that this endpoint allows providing a maximum of 5 run IDs per request. The bulk approach is more efficient than individual requests, but extremely large batches should be broken down into manageable chunks.

Memory and Storage: When downloading multiple audio files, consider the memory and storage requirements on your system. Implement appropriate streaming or chunked download strategies for large batches to avoid overwhelming your application’s resources.

By leveraging this bulk results endpoint, you can build more efficient applications that handle multiple text-to-sound generations seamlessly, enabling creative workflows that scale with your audio production needs.