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
  ]
}'
{
  "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"
      }
    ]
  }
}

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

Error Handling

The endpoint validates all provided run IDs before processing. If any run ID is invalid or corresponds to an incomplete conversion task, the entire request will return a validation error. Ensure all run IDs represent successfully completed story processing jobs before making bulk requests.

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

Response

200
application/json

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.