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

# Setup Story

> Initialize audiobook projects through the API for seamless editing and management in CAMB.AI Studio. This endpoint creates the foundation for your stories workflow by analyzing source text and establishing optimal narration parameters.

Transform your written content into professional audiobook projects with our Story Setup endpoint. This intelligent service bridges the gap between automated project initialization and creative audiobook production, allowing you to programmatically create story projects that seamlessly integrate with CAMB.AI Studio for detailed narration refinement and management.

Story Setup differs from direct story creation by building a project workspace rather than producing immediate results. Think of it as preparing a professional editing suite where creative teams can adjust pacing, refine pronunciation, and enhance overall audiobook quality.

## How it Works

Story Setup handles the technical foundation while preserving creative control. Your API request processes text analysis, configures narrator settings, and creates a Studio workspace with all preparation complete. Creative teams receive a ready-to-edit project rather than starting from raw text files.
The workflow naturally divides responsibilities between automated setup and creative refinement, enabling consistent project initialization while maintaining the flexibility needed for high-quality audiobook production.

## Quick Implementation

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

headers = {"x-api-key": "your-api-key"}

def create_audiobook_project(file_path, title, description, source_language, narrator_voice_id):
    """Creates audiobook project workspace in CAMB.AI Studio"""

    files = {'file': open(file_path, "rb")}
    data = {
        'title': title,
        'description': description,
        'source_language': source_language,
        'narrator_voice_id': narrator_voice_id
    }

    try:
        response = requests.post(
            "https://client.camb.ai/apis/story-setup",
            headers=headers, files=files, data=data
        )
        response.raise_for_status()
        result = response.json()

        print(f"Project created! Studio URL: {result.get('story_details', {}).get('studio_url')}")
        return result.get("run_id")

    except requests.exceptions.RequestException as e:
        print(f"Creation failed: {e}")
        return None
    finally:
        files['file'].close()

# Example usage
run_id = create_audiobook_project(
    "story.docx", # Replace with your local file path you are uploading.
    "My Audiobook Project",
    "Adventure story requiring dramatic narration",
    1,  # English
    147320
)
```

## Essential Configuration

Use clear project names and detailed descriptions to help Studio editors understand your content context and narration requirements. Verify language settings using the source languages endpoint and select narrator voices that match your content's tone and target audience.

Prepare documents with proper formatting and structure, as chapter organization and text quality directly impact the editing workflow. For specialized content with unique terminology, consider preparing pronunciation dictionaries to ensure consistent narration.

## When to Choose Story Setup

Use Story Setup for collaborative audiobook projects requiring creative refinement, quality control, or complex narration requirements. This endpoint excels when audiobook quality and team collaboration matter more than immediate results.

For simple, immediate narrated content without extensive editing needs, consider direct story creation instead. Story Setup provides the foundation for professional audiobook production where creative control and collaborative workflows drive the final quality.


## OpenAPI

````yaml post /story-setup
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /story-setup:
    post:
      tags:
        - APIs
        - Stories
      summary: Setup Story
      operationId: setup_story_story_setup_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/StorySetupResultResponse'
        '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
    StorySetupResultResponse:
      properties:
        run_id:
          type: integer
          minimum: 0
          title: Run ID
          description: >-
            The unique identifier for the run, which was generated during the
            Story setup process and returned upon task completion.
        story_details:
          $ref: '#/components/schemas/StoryDetails'
    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.
    StoryDetails:
      type: object
      properties:
        story_title:
          type: string
          title: Project Name
          minLength: 3
          maxLength: 255
          description: >-
            This represents the human-readable project identifier for your story
            project. Think of this as the project's display name that appears
            throughout CAMB.AI Studio, helping you and your team quickly
            identify which story content you're working with during the story
            creation process.
        story_description:
          type: string
          title: Project Description
          minLength: 3
          maxLength: 5000
          nullable: true
          description: >-
            This field contains the detailed project context and story synopsis
            you provided during setup, serving as documentation that travels
            with your audiobook project throughout its lifecycle. The
            description becomes particularly valuable for understanding the
            story's context, genre, and target audience when projects move
            between team members or when you return to work after time has
            passed.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: >-
            This timestamp in UTC timezone marks the exact moment your story
            project setup was initiated, providing crucial information for
            workflow coordination and project management throughout the
            narration process.
        source_language:
          $ref: '#/components/schemas/SourceLanguages'
          description: >-
            This identifies the original language of your story text content,
            representing one of the most critical configuration decisions that
            influences the AI narrator's pronunciation, intonation, and overall
            delivery quality during audiobook generation.
        target_languages:
          items:
            $ref: '#/components/schemas/Languages'
          type: array
          title: Target Languages
          description: >-
            This array contains all the languages you've requested for audiobook
            narration output. Each entry represents a different language version
            of your story that will be available as separate audio tracks in
            your CAMB.AI Studio project, allowing you to create multilingual
            audiobook versions from your original text.
        folder_id:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            This optional field indicates the organizational folder where your
            story resides within your team's workspace structure. Think of this
            as your project's filing location within CAMB.AI Studio, helping
            maintain organized project management as your audiobook library
            grows and you manage multiple story projects.
          example: <number>
        studio_url:
          type: string
          description: >-
            This field contains the direct URL link to access your audiobook
            project within CAMB.AI Studio's web interface. Once your project
            setup is complete, this URL serves as the primary entry point for
            all creative work, allowing you and your team members to navigate
            directly to the project's workspace where you can review generated
            audio, adjust narrator settings, refine pronunciation guides, manage
            chapter breaks, and oversee the entire audiobook production process.
    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
    Languages:
      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
        - 72
        - 73
        - 74
        - 75
        - 76
        - 77
        - 78
        - 79
        - 80
        - 81
        - 82
        - 83
        - 84
        - 85
        - 86
        - 87
        - 88
        - 89
        - 90
        - 91
        - 92
        - 93
        - 94
        - 95
        - 96
        - 97
        - 98
        - 99
        - 100
        - 101
        - 102
        - 103
        - 104
        - 105
        - 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
        - 147
        - 148
        - 149
        - 150
      title: Languages
      default: 1
  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.

````