Skip to main content
POST
/
text-to-sound-results
Get Sound and Music Results
curl --request POST \
  --url https://client.camb.ai/apis/text-to-sound-results \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "run_ids": [
    12345,
    6789
  ]
}
'
{
  "1234": {
    "output_url": "https://audio-storage.camb.ai/files/audio_1234.flac"
  },
  "5678": {
    "output_url": "https://audio-storage.camb.ai/files/audio_5678.flac"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.camb.ai/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint retrieves audio outputs generated from multiple previously completed Sound and Music 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.

Authorizations

​
x-api-key
string
header
required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Body

application/json
​
run_ids
integer[]
required

An array of unique positive integers, each representing the ID of a specific run. You must provide between 2 and 5 IDs, and all IDs must correspond to the same run type (e.g., all text-to-speech or all dubbing runs).

Required array length: 2 - 5 elements
Example:
[12345, 6789]

Response

Successful Response

An object containing the results of one to five text-to-sound runs. Each key in the object is a unique identifier for a run, and the corresponding value is the output for text-to-sound.

​
{key}
object