openapi.yaml

openapi: 3.1.0

info:
    title: Dream Machine API
    summary: A RESTful API for interacting with the Dream Machine
    description: Generate videos using Dream Machine.
    termsOfService: https://lumalabs.ai/legal/tos
    contact:
        name: Luma AI, Inc.
        email: support@lumalabs.ai
        url: https://lumalabs.ai
    license:
        name: Proprietary
        url: https://lumalabs.ai/legal/tos
    version: 1.1.0

servers:
    - url: https://api.lumalabs.ai/dream-machine/v1

security:
    - BearerAuth: []

components:
    securitySchemes:
        BearerAuth:
            type: http
            scheme: bearer
            bearerFormat: JWT
    schemas:
        Error:
            type: object
            description: The error object
            properties:
                detail:
                    type: string
                    description: The error message
            example:
                detail: 'Invalid API key is provided'

        State:
            type: string
            description: The state of the generation
            enum:
                - queued
                - dreaming
                - completed
                - failed
            example: completed

        ListGenerationResponse:
            type: object
            description: The generations response object
            properties:
                has_more:
                    type: boolean
                    description: Whether there are more generations
                count:
                    type: integer
                    description: The number of generations returned
                limit:
                    type: integer
                    description: The limit of the generations requested
                offset:
                    type: integer
                    description: The offset of the generations requested
                generations:
                    type: array
                    items:
                        $ref: '#/components/schemas/Generation'
                    description: The generations requested
            required:
                - generations
            example:
                has_more: false
                count: 1
                limit: 100
                offset: 0
                generations:
                    - id: '123e4567-e89b-12d3-a456-426614174000'
                      state: 'completed'
                      failure_reason: null
                      created_at: '2023-06-01T12:00:00Z'
                      assets:
                          video: 'https://example.com/video.mp4'
                      version: 'v1.6'
                      request:
                          prompt: 'A serene lake surrounded by mountains at sunset'
                          aspect_ratio: '16:9'
                          loop: true
                          keyframes:
                              frame0:
                                  type: image
                                  url: 'https://example.com/image.jpg'
                              frame1:
                                  type: generation
                                  id: '123e4567-e89b-12d3-a456-426614174000'

        GenerationReference:
            type: object
            description: The generation reference object
            properties:
                type:
                    type: string
                    enum:
                        - generation
                    default: generation
                id:
                    type: string
                    format: uuid
                    description: The ID of the generation
            required:
                - type
                - id
            example:
                type: generation
                id: '123e4567-e89b-12d3-a456-426614174000'

        ImageReference:
            type: object
            description: The image object
            properties:
                type:
                    type: string
                    enum:
                        - image
                    default: image
                url:
                    type: string
                    format: uri
                    description: The URL of the image
            required:
                - type
                - url
            example:
                type: image
                url: 'https://example.com/image.jpg'

        Assets:
            type: object
            description: The assets of the generation
            properties:
                video:
                    type: string
                    format: uri
                    description: The URL of the video
            example:
                video: 'https://example.com/video.mp4'

        AspectRatio:
            type: string
            enum:
                - '1:1'
                - '16:9'
                - '9:16'
                - '4:3'
                - '3:4'
                - '21:9'
                - '9:21'
            description: The aspect ratio of the generation
            example: '16:9'
            default: '16:9'

        GenerationRequest:
            type: object
            description: The generation request object
            properties:
                prompt:
                    type: string
                    description: The prompt of the generation
                aspect_ratio:
                    $ref: '#/components/schemas/AspectRatio'
                    description: The aspect ratio of the generation
                loop:
                    type: boolean
                    description: Whether to loop the video
                keyframes:
                    $ref: '#/components/schemas/Keyframes'
                    description: The keyframes of the generation
                callback_url:
                    type: string
                    format: uri
                    description: The callback URL of the generation, a POST request with Generation object will be sent to the callback URL when the generation is dreaming, completed, or failed
            examples:
                - summary: Text to video
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      loop: true
                - summary: Image to video
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      loop: false
                      keyframes:
                          frame0:
                              type: image
                              url: 'https://example.com/image.jpg'
                - summary: Image to video end frame
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      loop: false
                      keyframes:
                          frame1:
                              type: image
                              url: 'https://example.com/image.jpg'
                - summary: Image to video keyframes
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      keyframes:
                          frame0:
                              type: image
                              url: 'https://example.com/image.jpg'
                          frame1:
                              type: image
                              url: 'https://example.com/image.jpg'
                - summary: Extend video
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      loop: true
                      keyframes:
                          frame0:
                              type: generation
                              id: '123e4567-e89b-12d3-a456-426614174000'
                - summary: Extend video reverse
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      keyframes:
                          frame1:
                              type: generation
                              id: '123e4567-e89b-12d3-a456-426614174000'
                - summary: Interpolate image to video
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      keyframes:
                          frame0:
                              type: image
                              url: 'https://example.com/image.jpg'
                          frame1:
                              type: generation
                              id: '123e4567-e89b-12d3-a456-426614174000'
                - summary: Interpolate video to image
                  value:
                      prompt: 'A serene lake surrounded by mountains at sunset'
                      aspect_ratio: '16:9'
                      keyframes:
                          frame0:
                              type: generation
                              id: '123e4567-e89b-12d3-a456-426614174000'
                          frame1:
                              type: image
                              url: 'https://example.com/video.mp4'

        Generation:
            type: object
            description: The generation response object
            properties:
                id:
                    type: string
                    format: uuid
                    description: The ID of the generation
                state:
                    $ref: '#/components/schemas/State'
                    description: The state of the generation
                failure_reason:
                    type: string
                    description: The reason for the state of the generation
                created_at:
                    type: string
                    format: date-time
                    description: The date and time when the generation was created
                assets:
                    $ref: '#/components/schemas/Assets'
                    description: The assets of the generation
                version:
                    type: string
                    description: The model version used for the generation eg. v1.6
                request:
                    $ref: '#/components/schemas/GenerationRequest'
            example:
                id: '123e4567-e89b-12d3-a456-426614174000'
                state: 'completed'
                failure_reason: null
                created_at: '2023-06-01T12:00:00Z'
                assets:
                    video: 'https://example.com/video.mp4'
                version: 'v1.6'
                request:
                    prompt: 'A serene lake surrounded by mountains at sunset'
                    aspect_ratio: '16:9'
                    loop: true
                    keyframes:
                        frame0:
                            type: image
                            url: 'https://example.com/image.jpg'
                        frame1:
                            type: generation
                            id: '123e4567-e89b-12d3-a456-426614174000'

        Keyframe:
            oneOf:
                - $ref: '#/components/schemas/GenerationReference'
                - $ref: '#/components/schemas/ImageReference'
            discriminator:
                propertyName: type
                mapping:
                    generation: '#/components/schemas/GenerationReference'
                    image: '#/components/schemas/ImageReference'
            description: A keyframe can be either a Generation reference, an Image, or a Video
            examples:
                - summary: Generation reference
                  value:
                      type: generation
                      id: '123e4567-e89b-12d3-a456-426614174000'
                - summary: Image reference
                  value:
                      type: image
                      url: 'https://example.com/image.jpg'

        Keyframes:
            type: object
            description: The keyframes of the generation
            properties:
                frame0:
                    $ref: '#/components/schemas/Keyframe'
                    description: The frame 0 of the generation
                frame1:
                    $ref: '#/components/schemas/Keyframe'
                    description: The frame 1 of the generation
            example:
                frame0:
                    type: image
                    url: 'https://example.com/image.jpg'
                frame1:
                    type: generation
                    id: '123e4567-e89b-12d3-a456-426614174000'

        Credits:
            type: object
            description: The credits object
            properties:
                credit_balance:
                    type: number
                    format: float
                    description: Available credits balance in USD cents
            required:
                - credit_balance
paths:
    /ping:
        get:
            summary: Ping
            description: Check if the API is running
            operationId: ping
            tags:
                - Ping
            responses:
                '200':
                    description: API is running
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                        description: The message
                                example:
                                    message: 'pong'

    /generations:
        post:
            summary: Create a generation
            description: Initiate a new generation with the provided prompt
            operationId: createGeneration
            tags:
                - Generations
            requestBody:
                required: true
                description: The generation request object
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/GenerationRequest'
                        examples:
                            default:
                                value:
                                    prompt: 'A serene lake surrounded by mountains at sunset'
                                    aspect_ratio: '16:9'
                                    loop: true
                                    keyframes:
                                        frame0:
                                            type: image
                                            url: 'https://example.com/image.jpg'
                                        frame1:
                                            type: generation
                                            id: '123e4567-e89b-12d3-a456-426614174000'
            responses:
                '201':
                    description: Generation created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Generation'
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'

        get:
            summary: List generations
            description: Retrieve a list of generations with optional filtering and sorting
            operationId: listGenerations
            tags:
                - Generations
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 100
                - name: offset
                  in: query
                  required: false
                  schema:
                      type: integer
                      default: 0
            responses:
                '200':
                    description: Generations found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListGenerationResponse'
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'

    /generations/{id}:
        get:
            summary: Get a generation
            description: Retrieve details of a specific generation by its ID
            operationId: getGeneration
            tags:
                - Generations
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The ID of the generation
            responses:
                '200':
                    description: Generation found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Generation'
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'

        delete:
            summary: Delete a generation
            description: Remove a specific generation by its ID
            operationId: deleteGeneration
            tags:
                - Generations
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The ID of the generation
            responses:
                '204':
                    description: Generation deleted
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'

    /generations/camera_motion/list:
        get:
            summary: Get camera motions
            description: Get all possible camera motions
            operationId: getCameraMotion
            tags:
                - Generations
            responses:
                '200':
                    description: Camera motion found
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    type: string
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'

    /credits:
        get:
            summary: Get credits
            description: Get the credits information for the api user
            operationId: getCredits
            tags:
                - Credits
            responses:
                '200':
                    description: Credits found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Credits'
                default:
                    description: Error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'