Fetch Stories Results in Bulk

POST

stories-results

Get Stories Runs Results in Bulk

curl --request POST \
  --url https://client.camb.ai/apis/stories-results \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "run_ids": [
    12345,
    6789
  ]
}
'

import requests

url = "https://client.camb.ai/apis/stories-results"

payload = { "run_ids": [12345, 6789] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({run_ids: [12345, 6789]})
};

fetch('https://client.camb.ai/apis/stories-results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/stories-results",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'run_ids' => [
        12345,
        6789
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "1234": {
    "dialogue_url": "https://example.com/run/1234/dialogue.flac",
    "audio_url": "https://example.com/run/1234/audio.flac",
    "transcript": [
      {
        "start": 0.4,
        "end": 14.97,
        "text": "Olympus Mons is the largest volcano in the solar system.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 15.37,
        "end": 27.27,
        "text": "Its average slope is only about 5%.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 27.67,
        "end": 38.24,
        "text": "It may have once been an island surrounded by oceans.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 38.64,
        "end": 49.59,
        "text": "Future eruptions could still occur due to mantle activity.",
        "speaker": "SPEAKER_0"
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Streamline your workflow by retrieving results from multiple story conversion tasks in a single API call. This bulk endpoint eliminates the need for individual requests when managing large batches of story processing jobs, making it ideal for content management systems, automated publishing workflows, or analytics dashboards that need to aggregate story conversion results.

Bulk Processing Benefits

This endpoint provides several operational advantages:

Reduced API Calls: Fetch multiple story results with one request
Consistent Data Structure: Uniform response format across all stories
Efficient Resource Usage: Optimized for high-volume story retrieval
Batch Processing Support: Perfect for automated content pipelines

Request Structure

The endpoint accepts a JSON payload containing an array of run IDs from your story conversion tasks. Each run ID corresponds to a previously submitted story processing job.

All run IDs in the request must be valid and belong to completed story conversion tasks

Response Format

The API returns an array of story result objects, each containing the same structure as the individual story result endpoint:

Full Audio Narration: Complete audiobook-style recording (audio_url)
Dialogue-Only Track: Isolated character conversations (dialogue_url)
Time-Coded Transcript: Narrative transcript with speaker attribution (transcript)

All retrieved audio links become inaccessible after 24 hours

Example Python Implementation

Here’s how to fetch multiple story results efficiently using Python:

import requests
from typing import List, Dict, Optional

def fetch_bulk_story_results(run_ids: List[int]) -> Optional[List[Dict]]:
    """
    Retrieves multiple story conversion outputs in a single request

    Args:
        run_ids: List of unique run identifiers from story processing tasks

    Returns:
        List of story result dictionaries, or None if request fails
    """
    headers = {
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    payload = {
        "run_ids": run_ids
    }

    try:
        response = requests.post(
            "https://client.camb.ai/apis/stories-results",
            headers=headers,
            json=payload
        )
        response.raise_for_status()

        results = response.json()
        print(f"Retrieved {len(results)} story results successfully")

        return results

    except requests.exceptions.HTTPError as e:
        print(f"Error {e.response.status_code}: {e.response.text}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

def process_bulk_results(results: List[Dict]) -> None:
    """
    Process and display bulk story results

    Args:
        results: List of story result dictionaries
    """
    for i, story in enumerate(results, 1):
        print(story)
        print(f"\n--- Story {i} ---")
        print(f"Main Audio: {results[story]['audio_url']}")
        print(f"Dialogue Track: {results[story]['dialogue_url']}")

        if results[story].get('transcript'):
            print(f"Transcript entries: {len(results[story]['transcript'])}")
            # Preview first dialogue entry
            if results[story]['transcript']:
                first_entry = results[story]['transcript'][0]
                print(f"First line: [{first_entry['start']}-{first_entry['end']}ms] "
                      f"{first_entry['speaker']}: {first_entry['text'][:50]}...")

# Example usage with multiple run IDs
run_ids_to_fetch = [240320, 242604]

bulk_results = fetch_bulk_story_results(run_ids_to_fetch)

if bulk_results:
    process_bulk_results(bulk_results)

    # Example: Save audio URLs for batch download
    audio_urls = [bulk_results[story]['audio_url'] for story in bulk_results]
    print(f"\nExtracted {len(audio_urls)} audio URLs for batch processing")

Use Cases

This bulk endpoint is particularly valuable for:

Content Management Systems: Retrieving story assets for publication workflows
Analytics Dashboards: Aggregating conversion results for reporting
Automated Publishing: Batch processing completed stories for distribution
Quality Assurance: Bulk validation of story conversion outputs
Archive Management: Collecting completed story assets for long-term storage

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 story runs. Each key in the object is a unique identifier for a run, and the corresponding value is stories run output.

{key}

object

Hide child attributes

{key}.audio_url

string

The URL pointing to the generated audio file for the story.

{key}.dialogue_url

string

The URL pointing to the audio file that contains the story's dialogue.

{key}.transcript

DialogueItem · object[]

A collection of dialogue items representing the textual transcript of the story.

Hide child attributes

{key}.transcript.start

number<float>

required

The start time (in seconds) of the dialogue.

{key}.transcript.end

number<float>

required

The end time (in seconds) of the dialogue.

{key}.transcript.text

string

required

The actual text content of the dialogue spoken by the speaker.

{key}.transcript.speaker

string

required

The name or identifier of the speaker delivering the dialogue.

Last modified on May 16, 2026

Create Translated StoryCreates a translated story based on a previously generated story using the provided `run_id`

Get Stories Runs Results in Bulk

curl --request POST \
  --url https://client.camb.ai/apis/stories-results \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "run_ids": [
    12345,
    6789
  ]
}
'

import requests

url = "https://client.camb.ai/apis/stories-results"

payload = { "run_ids": [12345, 6789] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({run_ids: [12345, 6789]})
};

fetch('https://client.camb.ai/apis/stories-results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/stories-results",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'run_ids' => [
        12345,
        6789
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "1234": {
    "dialogue_url": "https://example.com/run/1234/dialogue.flac",
    "audio_url": "https://example.com/run/1234/audio.flac",
    "transcript": [
      {
        "start": 0.4,
        "end": 14.97,
        "text": "Olympus Mons is the largest volcano in the solar system.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 15.37,
        "end": 27.27,
        "text": "Its average slope is only about 5%.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 27.67,
        "end": 38.24,
        "text": "It may have once been an island surrounded by oceans.",
        "speaker": "SPEAKER_0"
      },
      {
        "start": 38.64,
        "end": 49.59,
        "text": "Future eruptions could still occur due to mantle activity.",
        "speaker": "SPEAKER_0"
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Getting Started

Models

Tutorials

SDK Guides

Hosting Platforms

Integrations

API Reference

Other Products

Release Logs

Fetch Stories Results in Bulk

Bulk Processing Benefits

Request Structure

Response Format

Example Python Implementation

Use Cases

Authorizations

Body

Response

​Bulk Processing Benefits

​Request Structure

​Response Format

​Example Python Implementation

​Use Cases

Authorizations

Body

Response

Bulk Processing Benefits

Request Structure

Response Format

Example Python Implementation

Use Cases