> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a Cast video



## OpenAPI

````yaml /api/openapi.json post /api/v1/cast/videos
openapi: 3.0.2
info:
  title: Melius API
  version: '1'
  description: >-
    The Melius REST API. Authenticate with an API key as a bearer token
    (`Authorization: Bearer mel_...`) and select the team to act on with the
    `x-team-id` header. Generations run through the same node + run pipeline as
    the app: create a node on a canvas, start a run, poll the run, then read the
    resulting version asset.
servers:
  - url: https://api.melius.com
security:
  - apiKey: []
    teamId: []
paths:
  /api/v1/cast/videos:
    post:
      tags:
        - cast
      summary: Start a Cast video
      operationId: cast.run
      parameters:
        - in: header
          name: idempotency-key
          description: >-
            A case-sensitive key for one intended submission: 1–255 ASCII
            letters, digits, periods, underscores, colons or hyphens. Reuse it
            for identical retries; use a fresh key for a new run.
          schema:
            type: string
            pattern: ^[A-Za-z0-9._:-]+$
            minLength: 1
            maxLength: 255
            description: >-
              A case-sensitive key for one intended submission: 1–255 ASCII
              letters, digits, periods, underscores, colons or hyphens. Reuse it
              for identical retries; use a fresh key for a new run.
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                attemptId:
                  type: string
                  format: uuid
                preparationToken:
                  type: string
                  format: uuid
                expectedEstimatedCredits:
                  type: number
                  minimum: 0
                input:
                  type: object
                  properties:
                    avatar:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - custom
                            - curated
                            - element
                        id:
                          type: string
                          format: uuid
                      required:
                        - kind
                        - id
                      additionalProperties: false
                    voice:
                      oneOf:
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - stock
                            voiceId:
                              type: string
                              minLength: 1
                              maxLength: 200
                          required:
                            - kind
                            - voiceId
                          additionalProperties: false
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - custom
                            customVoiceId:
                              type: string
                              format: uuid
                          required:
                            - kind
                            - customVoiceId
                          additionalProperties: false
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - auto
                          required:
                            - kind
                          additionalProperties: false
                    voiceName:
                      type: string
                      maxLength: 200
                    otherAvatars:
                      type: array
                      items:
                        type: object
                        properties:
                          kind:
                            type: string
                            enum:
                              - custom
                              - curated
                              - element
                          id:
                            type: string
                            format: uuid
                          voice:
                            oneOf:
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    enum:
                                      - stock
                                  voiceId:
                                    type: string
                                    minLength: 1
                                    maxLength: 200
                                required:
                                  - kind
                                  - voiceId
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    enum:
                                      - custom
                                  customVoiceId:
                                    type: string
                                    format: uuid
                                required:
                                  - kind
                                  - customVoiceId
                                additionalProperties: false
                          voiceName:
                            type: string
                            maxLength: 200
                        required:
                          - kind
                          - id
                        additionalProperties: false
                      minItems: 1
                      maxItems: 2
                    tone:
                      type: string
                      minLength: 1
                      maxLength: 200
                    engine:
                      type: string
                      enum:
                        - seedance
                      default: seedance
                    resolution:
                      oneOf:
                        - type: string
                          enum:
                            - 360p
                            - 480p
                            - 540p
                            - 580p
                            - 720p
                            - 480P
                            - 768P
                            - 1080P
                            - 1080p
                            - 1440p
                            - 2160p
                            - 4k
                            - 0.5K
                            - 1K
                            - 2K
                            - 4K
                            - 1k
                            - 2k
                        - type: string
                    subtitles:
                      type: object
                      properties:
                        preset:
                          type: string
                          enum:
                            - simple
                            - plain
                            - beans
                            - corpo
                            - boo
                            - shadeplay
                            - casper
                            - capri
                            - lowkey
                            - vinta
                            - diego
                            - ali
                            - slay
                            - kitty
                            - hustle
                            - karl
                            - sprout
                            - flex
                            - mint
                            - rizz
                            - vegas
                            - glass
                            - whisper
                            - glide2
                            - fusion
                            - glide
                            - terminal
                            - handwritten
                        language:
                          type: string
                        position:
                          type: string
                          enum:
                            - top
                            - center
                            - bottom
                        textCustomizations:
                          type: object
                          properties:
                            baseline:
                              type: object
                              properties:
                                font:
                                  type: string
                                weight:
                                  type: integer
                                color:
                                  type: string
                            highlighted:
                              type: object
                              properties:
                                font:
                                  type: string
                                weight:
                                  type: integer
                                color:
                                  type: string
                      required:
                        - preset
                    creationSettings:
                      type: object
                      properties:
                        videoStyle:
                          type: object
                          properties:
                            id:
                              type: string
                              enum:
                                - auto
                                - self-filmed
                                - produced
                                - drama
                                - vlog
                                - podcast
                                - unboxing
                                - tutorial
                                - announcement
                                - explainer
                                - founder-story
                                - before-after
                                - corporate-training
                                - storytime
                                - comment-reply
                                - streamer-reaction
                                - animated-3d
                                - street-interview
                            version:
                              type: number
                              enum:
                                - 1
                          required:
                            - id
                            - version
                        speech:
                          type: string
                          enum:
                            - on-screen
                            - narration
                        visuals:
                          type: string
                          enum:
                            - auto
                            - 'on'
                            - 'off'
                          description: >-
                            Auto chooses useful supporting visuals from the
                            script, actions and props across video styles, and
                            may keep generated footage alone. Off skips added
                            visuals. On remains accepted for compatibility.
                            Subtitles are separate; generation eligibility still
                            applies.
                        pronunciations:
                          type: array
                          items:
                            type: object
                            properties:
                              word:
                                type: string
                                minLength: 1
                                maxLength: 200
                              pronunciation:
                                type: string
                                minLength: 1
                                maxLength: 200
                            required:
                              - word
                              - pronunciation
                          maxItems: 50
                          description: >-
                            Confirmed spoken spellings, e.g.
                            [{"word":"Emmaus","pronunciation":"ee-may-us"}].
                            Applied to speech only; keep the original spelling
                            in the script and visual directions.
                      required:
                        - videoStyle
                        - speech
                    scriptTemplate:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        revision:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        source:
                          type: string
                          enum:
                            - database
                      required:
                        - id
                        - revision
                        - source
                    sections:
                      type: array
                      items:
                        type: object
                        properties:
                          title:
                            type: string
                            maxLength: 200
                          text:
                            type: string
                            maxLength: 5000
                          action:
                            type: string
                            maxLength: 2000
                          kind:
                            type: string
                            enum:
                              - action
                          cutaway:
                            type: boolean
                            enum:
                              - true
                          seconds:
                            type: integer
                            minimum: 1
                            maximum: 8
                          speakerId:
                            type: string
                            maxLength: 200
                          scene:
                            type: string
                            maxLength: 2000
                        required:
                          - text
                        additionalProperties: false
                      minItems: 1
                      maxItems: 30
                    backgroundId:
                      type: string
                      format: uuid
                    propAssetId:
                      type: string
                      format: uuid
                    propName:
                      type: string
                      maxLength: 200
                    props:
                      type: array
                      items:
                        type: object
                        properties:
                          assetId:
                            type: string
                            format: uuid
                          name:
                            type: string
                            minLength: 1
                            maxLength: 200
                        required:
                          - assetId
                        additionalProperties: false
                      minItems: 1
                      maxItems: 6
                    aspectRatio:
                      type: string
                      enum:
                        - '21:9'
                        - '20:9'
                        - 19.5:9
                        - '2:1'
                        - '16:9'
                        - '3:2'
                        - '4:3'
                        - '5:4'
                        - '1:1'
                        - '4:5'
                        - '3:4'
                        - '2:3'
                        - '9:16'
                        - '1:2'
                        - '9:19.5'
                        - '9:20'
                        - '9:21'
                      default: '9:16'
                    workId:
                      type: string
                      format: uuid
                  required:
                    - avatar
                    - voice
                    - sections
                  additionalProperties: false
              required:
                - attemptId
                - input
              additionalProperties: false
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      generationId:
                        type: string
                        format: uuid
                      canvasId:
                        type: string
                        format: uuid
                      bulkNodeRunId:
                        type: string
                        format: uuid
                      videoNodeId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - submitting
                    required:
                      - generationId
                      - canvasId
                      - bulkNodeRunId
                      - videoNodeId
                      - status
                  - type: object
                    properties:
                      generationId:
                        type: string
                        format: uuid
                      canvasId:
                        type: string
                        format: uuid
                      bulkNodeRunId:
                        type: string
                        format: uuid
                      videoNodeId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - running
                    required:
                      - generationId
                      - canvasId
                      - bulkNodeRunId
                      - videoNodeId
                      - status
                  - type: object
                    properties:
                      generationId:
                        type: string
                        format: uuid
                      canvasId:
                        type: string
                        format: uuid
                      bulkNodeRunId:
                        type: string
                        format: uuid
                      videoNodeId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - captioning
                    required:
                      - generationId
                      - canvasId
                      - bulkNodeRunId
                      - videoNodeId
                      - status
                  - type: object
                    properties:
                      generationId:
                        type: string
                        format: uuid
                      canvasId:
                        type: string
                        format: uuid
                      bulkNodeRunId:
                        type: string
                        format: uuid
                      videoNodeId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - ready
                      outputVersionId:
                        type: string
                        format: uuid
                      assetId:
                        type: string
                        format: uuid
                      url:
                        type: string
                      warning:
                        type: string
                    required:
                      - generationId
                      - canvasId
                      - bulkNodeRunId
                      - videoNodeId
                      - status
                      - outputVersionId
                      - assetId
                      - url
                  - type: object
                    properties:
                      generationId:
                        type: string
                        format: uuid
                      canvasId:
                        type: string
                        format: uuid
                      bulkNodeRunId:
                        type: string
                        format: uuid
                      videoNodeId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - failed
                      message:
                        type: string
                    required:
                      - generationId
                      - canvasId
                      - bulkNodeRunId
                      - videoNodeId
                      - status
                      - message
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                required:
                  - statusCode
                  - message
        '402':
          description: '402'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '409':
          description: '409'
          headers:
            Retry-After:
              description: >-
                Present for IDEMPOTENCY_REQUEST_IN_PROGRESS: wait one second,
                then retry with the same key and request.
              schema:
                type: integer
                enum:
                  - 1
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      message:
                        type: string
                      code:
                        type: string
                        enum:
                          - IDEMPOTENCY_KEY_REUSED
                          - IDEMPOTENCY_REQUEST_IN_PROGRESS
                      retryAfterSeconds:
                        type: number
                    required:
                      - message
                      - code
                  - type: object
                    properties:
                      message:
                        type: string
                    required:
                      - message
        '429':
          description: Rate limit reached — retry after the `Retry-After` header.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                  retryAfterSeconds:
                    type: integer
                required:
                  - statusCode
                  - message
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A Melius API key (`mel_...`), sent as `Authorization: Bearer <key>`.'
    teamId:
      type: apiKey
      in: header
      name: x-team-id
      description: The team (workspace) to act on. Defaults to the key's team when omitted.

````

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