> ## 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.
# Fetch Stories Results in Bulk
> Efficiently retrieve multiple story conversion outputs simultaneously using a collection of run identifiers
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:
```python [expandable] theme={null}
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
## OpenAPI
````yaml post /stories-results
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/stories-results:
post:
tags:
- APIs
- Stories
summary: Get Stories Runs Results in Bulk
operationId: get_stories_runs_results_stories_results_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunIDsRequestPayload'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkStoriesRunsResults'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
RunIDsRequestPayload:
properties:
run_ids:
items:
type: integer
exclusiveMinimum: 0
type: array
maxItems: 5
minItems: 2
uniqueItems: true
title: Run IDs
description: >-
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).
example:
- 12345
- 6789
type: object
required:
- run_ids
title: RunIDsRequestPayload
BulkStoriesRunsResults:
type: object
title: BulkStoriesRunsResults
additionalProperties:
$ref: '#/components/schemas/StoryRunInfoResponse'
minProperties: 1
maxProperties: 5
description: >-
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.
example:
'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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
StoryRunInfoResponse:
properties:
audio_url:
type: string
title: Story Output Audio URL
description: The URL pointing to the generated audio file for the story.
dialogue_url:
type: string
title: Story Dialogue Audio URL
description: >-
The URL pointing to the audio file that contains the story's
dialogue.
transcript:
type: array
items:
$ref: '#/components/schemas/DialogueItem'
title: Story Transcript
description: >-
A collection of dialogue items representing the textual transcript
of the story.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
DialogueItem:
type: object
description: >-
A JSON that represents a single piece of dialogue or speech within a
given time range. It includes details about the timing (start and end),
the content of the dialogue (text), and the speaker who delivers the
dialogue
properties:
start:
type: number
format: float
title: Start Time
description: The start time (in seconds) of the dialogue.
end:
type: number
format: float
title: End Time
description: The end time (in seconds) of the dialogue.
text:
type: string
title: Dialogue Text
description: The actual text content of the dialogue spoken by the speaker.
speaker:
type: string
title: Speaker Name
description: The name or identifier of the speaker delivering the dialogue.
required:
- start
- end
- text
- speaker
title: DialogueItem
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
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.
````