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

> Narrate a video with a chosen voice, from your script or a generated one.

Unlike the other endpoints here, narration creates a new run rather than acting on one, so it takes a `project_name`, `project_description` and `folder_id`.

Point `video_url` at the video and set `video_type` to say what it is. Supply `script_file_key` to narrate a script you have written, or omit it to have one written for you. `narration_type` picks between reading a script (`narration`) and describing what is on screen (`audio_description`). `narrator_voice_id` chooses the voice, and `remove_fg_audio` decides whether the original foreground audio stays under the narration.

Track progress by polling [`/narration/{task_id}`](get-narration-status) with the `task_id` returned in the response.


## OpenAPI

````yaml post /narration
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /narration:
    post:
      tags:
        - Narration
      summary: Create Narration
      operationId: create_narration_narration_post
      parameters:
        - name: traceparent
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Traceparent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNarrationRequestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrchestratorPipelineCallResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    CreateNarrationRequestPayload:
      properties:
        project_name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 3
            - type: 'null'
          title: Project Name
        project_description:
          anyOf:
            - type: string
              maxLength: 5000
              minLength: 3
            - type: 'null'
          title: Project Description
        folder_id:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: 'null'
          title: Folder Id
        narration_type:
          $ref: '#/components/schemas/NarrationType'
          description: >-
            NARRATION reads a script; AUDIO_DESCRIPTION describes what is on
            screen.
          default: narration
        video_url:
          type: string
          title: Video Url
          description: Video to narrate, as a public or bucket URL.
        video_type:
          $ref: '#/components/schemas/LinkVideoTypes'
          description: Where video_url points.
        video_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Video Id
          description: Platform video id. Derived from video_url when omitted.
        source_language:
          $ref: '#/components/schemas/Languages'
          description: Language spoken in the video.
        narrator_voice_id:
          type: integer
          exclusiveMinimum: 0
          title: Narrator Voice Id
          description: Voice that reads the narration.
        script_file_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Script File Key
          description: Bucket key of a narration script. Omit to have one written.
        remove_fg_audio:
          type: boolean
          title: Remove Fg Audio
          description: Drop the original foreground audio under the narration.
          default: true
        chosen_dictionaries:
          anyOf:
            - items:
                type: integer
                exclusiveMinimum: 0
              type: array
            - type: 'null'
          title: Chosen Dictionaries
          description: Dictionaries applied to the narration.
        speech_model:
          anyOf:
            - type: string
              enum:
                - mars-pro
                - mars-81
                - mars-8.1-pro-beta
                - mars-8.1-flash-beta
                - mars-81-flash
                - mars-flash
                - mars-instruct
                - mars-x-instruct
                - mars-x.b-instruct
            - type: 'null'
          title: Speech Model
          description: >-
            Speech model used to read the narration. Same choices as the
            /tts-stream API (e.g. mars-pro, mars-81, mars-81-flash,
            mars-instruct). Omit to let the system choose automatically.
      type: object
      required:
        - video_url
        - video_type
        - source_language
        - narrator_voice_id
      title: CreateNarrationRequestPayload
    OrchestratorPipelineCallResult:
      properties:
        task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Task Id
      type: object
      required:
        - task_id
      title: OrchestratorPipelineCallResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    NarrationType:
      type: string
      enum:
        - narration
        - audio_description
      title: NarrationType
    LinkVideoTypes:
      type: integer
      enum:
        - 0
        - 1
        - 2
        - 3
      title: LinkVideoTypes
    Languages:
      type: integer
      title: Language ID
      description: >-
        Numeric language ID. Use [`GET
        /source-languages`](/api-reference/endpoint/get-source-languages) for
        valid `source_language` values and [`GET
        /target-languages`](/api-reference/endpoint/get-target-languages) for
        valid output `language` values. For example, `1` is English (US) and
        `54` is Spanish (Spain).
    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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.