> ## 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.

# Create Story

> Creates a story based on the content provided in a text file (`.txt`) or Word document (`.docx`)

Transform your written content into engaging narrated stories with our story creation endpoint. This powerful service takes your text documents and processes them into compelling stories with professional narration. The system handles the entire process from parsing your document to generating a professionally narrated version, making storytelling accessible.

## The Story Creation Process

When you submit a story creation request, our system begins a multi-stage workflow:

<Steps>
  <Step title="Document Processing">
    Your uploaded text file or Word document is processed and prepared for narration. Our system extracts and analyzes the content, ensuring proper formatting and structure.
  </Step>

  <Step title="Voice Selection">
    Your chosen AI narrator voice is applied to the story, bringing your content to life with natural-sounding speech patterns and appropriate emotional delivery.
  </Step>

  <Step title="Audio Production">
    The narration is finalized with professional audio quality enhancements, ensuring clarity and engagement.
  </Step>
</Steps>

Throughout this process, you can check on your task's progress using the [`/story/{task_id}`](get-story-status) endpoint with the `task_id` provided in your initial response.

## Supported Document Formats

Our story creation service accepts two popular document formats to accommodate your workflow:

| Document Type  | Supported Formats |
| :------------- | :---------------- |
| Text Files     | .txt              |
| Word Documents | .docx             |

This flexibility allows you to work with your preferred writing tools without conversion hassles.

## Language Configuration

Specifying the correct source language is crucial for successful story creation. To find the appropriate language identifier:

1. Query the [`/source-languages`](get-source-languages) endpoint for a complete list of supported languages.
2. Use the returned language ID in your request to ensure accurate processing.

## Creating Your First Story

Let's look at how to initiate a story creation task with Python:

```python [expandable] theme={null}
import requests
import json

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# Define your story parameters
title = "The Midnight Garden"
description = "A mysterious tale of discovery and wonder"
source_language = 1  # Example: English (check /languages for IDs)
narrator_voice_id = 147320  # Example

# Function to submit a story creation request
def create_story(file_path, title, description, source_language, narrator_voice_id):
    """
    Submits a new story creation task and returns the task ID for tracking.

    Parameters:
    - file_path: Path to the .txt or .docx file containing story content
    - title: Title of the story
    - description: Brief description of the story
    - source_language: Language ID for the story content
    - narrator_voice_id: ID of the voice that will narrate the story
    """
    try:
        # Prepare the multipart form data
        files = {
            'file': (file_path.split('/')[-1], open(file_path, 'rb'))
        }

        data = {
            'title': title,
            'description': description,
            'source_language': source_language,
            'narrator_voice_id': narrator_voice_id
        }

        # Submit the request
        response = requests.post(
            "https://client.camb.ai/apis/story",
            headers=headers,
            files=files,
            data=data
        )

        # Verify the request was successful
        response.raise_for_status()

        # Extract the task ID from the response
        result = response.json()
        task_id = result.get("task_id")

        print(f"Story creation task submitted successfully! Task ID: {task_id}")
        return task_id

    except requests.exceptions.RequestException as e:
        print(f"Error submitting story creation task: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None
    finally:
        # Make sure to close the file
        if 'files' in locals() and 'file' in files:
            files['file'][1].close()

# Call the function with your story file
file_path = "path/to/your/story.docx"  # Replace with your actual file path
task_id = create_story(file_path, title, description, source_language, narrator_voice_id)
```

## Monitoring Your Story Creation Progress

After submission, your content enters our processing pipeline. The time required depends on the length and complexity of your document. You can check progress by polling the status endpoint:

```python [expandable] theme={null}
def check_story_status(task_id):
    """
    Checks the status of a story creation task.
    Returns the current status and any available result information.

    Parameters:
    - task_id: The ID of the story creation task to check
    """
    if not task_id:
        print("No task ID provided.")
        return None

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/story/{task_id}",
            headers=headers
        )

        # Verify the request was successful
        response.raise_for_status()

        # Parse the status information
        status_data = response.json()
        print(f"Current status: {status_data['status']}")

        # If the story is complete, display the results
        if status_data['status'] == "SUCCESS":
            print("Story creation completed successfully!")
            print(f"Story URL: {status_data.get('story_url')}")

        return status_data

    except requests.exceptions.RequestException as e:
        print(f"Error checking story status: {e}")
        return None

# Check the status of your story creation task
status_info = check_story_status(task_id)
```

## Best Practices for Optimal Results

To get the most from our story creation service, consider these professional tips:

1. **Document Quality**: Ensure your document is well-formatted with proper grammar and punctuation for better narration results.

2. **Voice Selection**: Choose a narrator voice that matches the tone and style of your story content.

3. **Language Accuracy**: Double-check that your source language is correctly specified to ensure proper pronunciation and pacing.

4. **Content Length**: While our system can handle documents of various lengths, consider breaking very long works into logical segments for optimal processing.

5. **File Format**: Use .docx format when you need to preserve complex formatting, and .txt for simpler text-based stories.

## Practical Applications

Our story creation functionality opens exciting possibilities across industries:

* **Education**: Transform educational content into engaging audio lessons for diverse learning styles.
* **Publishing**: Quickly create audio versions of books, articles, and short stories.
* **Content Creation**: Convert blog posts and articles into narrated content for podcasts or audio platforms.
* **Accessibility**: Make written content accessible to visually impaired audiences or those who prefer audio content.
* **Entertainment**: Bring original stories to life with professional-quality narration.

By integrating this API into your workflow, you can efficiently transform written content into engaging audio stories, dramatically reducing the time and expense traditionally associated with professional narration while maintaining impressive quality.


## OpenAPI

````yaml post /story
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /story:
    post:
      tags:
        - Apis
        - Stories
      summary: Create Story
      operationId: create_story_story_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateStoryRequestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
                description: >-
                  A JSON that contains the unique identifier for the task. This
                  is used to query the status of the end to end dubbing task
                  that is running. It is returned when a create request is made
                  for a story.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    CreateStoryRequestPayload:
      allOf:
        - type: object
          properties:
            file:
              type: string
              format: binary
              title: File
              description: >-
                The text file (`.txt`) or Word document (`.docx`) containing
                your story content. This document will be used as the basis for
                the audio book.
            title:
              type: string
              title: Title
              description: >-
                A descriptive title for your story, making it easier to identify
                and organize.
              minLength: 3
              maxLength: 255
              nullable: true
              default: null
            description:
              type: string
              title: Description
              description: >-
                A brief synopsis of your story, helping to set context and
                expectations.
              minLength: 3
              maxLength: 5000
              nullable: true
              default: null
            source_language:
              $ref: '#/components/schemas/SourceLanguages'
              title: Source Language
              description: >-
                The language of the contents in the input file. This helps our
                system accurately process and narrate your content.
            narrator_voice_id:
              type: integer
              title: Narrator Voice ID
              description: >-
                The identifier of the AI voice that will narrate your story.
                This determines the tone, accent, and delivery style.
              default: 147320
            chosen_dictionaries:
              $ref: '#/components/schemas/ChosenDictionariesSchema'
          required:
            - file
            - source_language
      title: CreateStoryRequestPayload
    TaskID:
      properties:
        task_id:
          type: string
          title: Task ID
      type: object
      title: Task ID
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SourceLanguages:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
        - 11
        - 12
        - 13
        - 14
        - 15
        - 16
        - 17
        - 18
        - 19
        - 20
        - 21
        - 22
        - 23
        - 24
        - 25
        - 26
        - 27
        - 28
        - 29
        - 30
        - 31
        - 32
        - 33
        - 34
        - 35
        - 36
        - 37
        - 38
        - 39
        - 40
        - 41
        - 42
        - 43
        - 44
        - 45
        - 46
        - 47
        - 48
        - 49
        - 50
        - 51
        - 52
        - 53
        - 54
        - 55
        - 56
        - 57
        - 58
        - 59
        - 60
        - 61
        - 62
        - 63
        - 64
        - 65
        - 66
        - 67
        - 68
        - 69
        - 70
        - 71
        - 73
        - 74
        - 75
        - 76
        - 78
        - 79
        - 80
        - 81
        - 82
        - 83
        - 84
        - 85
        - 86
        - 87
        - 88
        - 90
        - 91
        - 92
        - 93
        - 94
        - 95
        - 96
        - 97
        - 98
        - 99
        - 100
        - 101
        - 102
        - 103
        - 104
        - 106
        - 107
        - 108
        - 109
        - 110
        - 111
        - 112
        - 113
        - 114
        - 115
        - 116
        - 117
        - 118
        - 119
        - 120
        - 121
        - 122
        - 123
        - 124
        - 125
        - 126
        - 127
        - 128
        - 129
        - 130
        - 131
        - 132
        - 133
        - 134
        - 135
        - 136
        - 139
        - 140
        - 141
        - 142
        - 143
        - 144
        - 145
        - 146
        - 148
      default: 1
    ChosenDictionariesSchema:
      type: array
      nullable: true
      items:
        type: integer
      uniqueItems: true
      minItems: 1
      default: null
      description: >-
        An optional list of dictionary IDs selected by the user. Each entry must
        be an integer corresponding to a valid dictionary ID. If provided, at
        least one ID is required.
    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
  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.

````