---
updatedAt: 2026-07-10T19:01:19.000Z
---

Fetch the complete documentation index at: https://docs.lumalabs.ai/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Create a generation

Initiate a new generation with the provided prompt

<Callout icon="🚀" theme="default">
  ### Looking for the latest Luma API?

  Create and manage API access in the [Luma API Platform](https://platform.lumalabs.ai/). For current API guides and reference, visit the [Luma Agents API documentation](https://docs.agents.lumalabs.ai/).
</Callout>

# OpenAPI definition

```json
{
  "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"
      },
      "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-426614174003"
        }
      },
      "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"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the image"
          },
          "progress_video": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the progress video"
          }
        },
        "examples": [
          {
            "summary": "Video",
            "value": {
              "video": "https://example.com/video.mp4"
            }
          },
          {
            "summary": "Image",
            "value": {
              "image": "https://example.com/image.jpg"
            }
          }
        ]
      },
      "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"
      },
      "VideoModel": {
        "type": "string",
        "enum": [
          "ray-2",
          "ray-flash-2"
        ],
        "default": "ray-2",
        "example": "ray-2",
        "description": "The video model used for the generation"
      },
      "VideoModelOutputResolution": {
        "anyOf": [
          {
            "type": "string",
            "enum": [
              "540p",
              "720p",
              "1080p",
              "4k"
            ]
          },
          {
            "type": "string"
          }
        ]
      },
      "VideoModelOutputDuration": {
        "anyOf": [
          {
            "type": "string",
            "enum": [
              "5s",
              "9s"
            ]
          },
          {
            "type": "string"
          }
        ]
      },
      "Concept": {
        "type": "object",
        "description": "The concept object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The key of the concept"
          }
        },
        "required": [
          "key"
        ]
      },
      "GenerationRequest": {
        "type": "object",
        "description": "The generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "video"
            ],
            "default": "video"
          },
          "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"
          },
          "model": {
            "$ref": "#/components/schemas/VideoModel",
            "description": "The model used for the generation"
          },
          "resolution": {
            "$ref": "#/components/schemas/VideoModelOutputResolution",
            "description": "The resolution of the generation"
          },
          "duration": {
            "$ref": "#/components/schemas/VideoModelOutputDuration",
            "description": "The duration of the generation"
          },
          "concepts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Concept"
            },
            "description": "The concepts of the generation"
          }
        },
        "required": [
          "model"
        ],
        "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"
                }
              }
            }
          }
        ]
      },
      "Media": {
        "type": "object",
        "description": "The image entity object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the media"
          }
        },
        "required": [
          "url"
        ]
      },
      "ReframeImageModels": {
        "type": "string",
        "enum": [
          "photon-1",
          "photon-flash-1"
        ],
        "description": "The model used for the reframe image"
      },
      "ReframeVideoModels": {
        "type": "string",
        "enum": [
          "ray-2",
          "ray-flash-2"
        ],
        "description": "The model used for the reframe video"
      },
      "ReframeImageRequest": {
        "type": "object",
        "description": "The reframe image generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "reframe_image"
            ],
            "default": "reframe_image"
          },
          "media": {
            "$ref": "#/components/schemas/Media"
          },
          "model": {
            "$ref": "#/components/schemas/ReframeImageModels",
            "description": "The model used for the reframe image"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt of the generation",
            "default": ""
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio",
            "description": "The aspect ratio of the generation"
          },
          "grid_position_x": {
            "type": "integer",
            "description": "The x position of the image in the grid"
          },
          "grid_position_y": {
            "type": "integer",
            "description": "The y position of the image in the grid"
          },
          "x_start": {
            "type": "integer",
            "description": "The x start of the crop bounds"
          },
          "x_end": {
            "type": "integer",
            "description": "The x end of the crop bounds"
          },
          "y_start": {
            "type": "integer",
            "description": "The y start of the crop bounds"
          },
          "y_end": {
            "type": "integer",
            "description": "The y end of the crop bounds"
          },
          "resized_width": {
            "type": "integer",
            "description": "Resized width of source image"
          },
          "resized_height": {
            "type": "integer",
            "description": "Resized height of source image"
          },
          "format": {
            "$ref": "#/components/schemas/ImageFormat",
            "description": "The format of the image"
          },
          "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"
          }
        },
        "required": [
          "media",
          "aspect_ratio",
          "model",
          "generation_type"
        ]
      },
      "ModifyVideoModel": {
        "type": "string",
        "enum": [
          "ray-2",
          "ray-flash-2"
        ],
        "description": "The model used for the modify video"
      },
      "ModifyVideoMode": {
        "type": "string",
        "enum": [
          "adhere_1",
          "adhere_2",
          "adhere_3",
          "flex_1",
          "flex_2",
          "flex_3",
          "reimagine_1",
          "reimagine_2",
          "reimagine_3"
        ],
        "description": "The mode of the modify video"
      },
      "ModifyVideoRequest": {
        "type": "object",
        "description": "The modify video generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "modify_video"
            ],
            "default": "modify_video"
          },
          "media": {
            "$ref": "#/components/schemas/Media"
          },
          "first_frame": {
            "$ref": "#/components/schemas/Media"
          },
          "model": {
            "$ref": "#/components/schemas/ModifyVideoModel",
            "description": "The model used for the modify video"
          },
          "mode": {
            "$ref": "#/components/schemas/ModifyVideoMode",
            "description": "The mode of the modify video"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt 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"
          }
        },
        "required": [
          "media",
          "model",
          "mode",
          "generation_type"
        ]
      },
      "ReframeVideoRequest": {
        "type": "object",
        "description": "The reframe video generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "reframe_video"
            ],
            "default": "reframe_video"
          },
          "media": {
            "$ref": "#/components/schemas/Media"
          },
          "first_frame": {
            "$ref": "#/components/schemas/Media"
          },
          "model": {
            "$ref": "#/components/schemas/ReframeVideoModels",
            "description": "The model used for the reframe video"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt of the generation",
            "default": ""
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio",
            "description": "The aspect ratio of the generation"
          },
          "grid_position_x": {
            "type": "integer",
            "description": "The x position of the image in the grid"
          },
          "grid_position_y": {
            "type": "integer",
            "description": "The y position of the image in the grid"
          },
          "x_start": {
            "type": "integer",
            "description": "The x start of the crop bounds"
          },
          "x_end": {
            "type": "integer",
            "description": "The x end of the crop bounds"
          },
          "y_start": {
            "type": "integer",
            "description": "The y start of the crop bounds"
          },
          "y_end": {
            "type": "integer",
            "description": "The y end of the crop bounds"
          },
          "resized_width": {
            "type": "integer",
            "description": "Resized width of source video"
          },
          "resized_height": {
            "type": "integer",
            "description": "Resized height of source video"
          },
          "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"
          }
        },
        "required": [
          "media",
          "aspect_ratio",
          "model",
          "generation_type"
        ]
      },
      "GenerationType": {
        "type": "string",
        "enum": [
          "video",
          "image"
        ]
      },
      "Generation": {
        "type": "object",
        "description": "The generation response object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The ID of the generation"
          },
          "generation_type": {
            "$ref": "#/components/schemas/GenerationType",
            "description": "The type of the generation",
            "default": "video"
          },
          "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"
          },
          "model": {
            "type": "string",
            "description": "The model used for the generation"
          },
          "request": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GenerationRequest"
              },
              {
                "$ref": "#/components/schemas/ImageGenerationRequest"
              },
              {
                "$ref": "#/components/schemas/UpscaleVideoGenerationRequest"
              },
              {
                "$ref": "#/components/schemas/AudioGenerationRequest"
              },
              {
                "$ref": "#/components/schemas/ReframeImageRequest"
              },
              {
                "$ref": "#/components/schemas/ReframeVideoRequest"
              },
              {
                "$ref": "#/components/schemas/ModifyVideoRequest"
              }
            ],
            "description": "The request of the generation"
          }
        },
        "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"
          },
          "model": "ray-2",
          "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"
          }
        }
      },
      "ImageRef": {
        "type": "object",
        "description": "The image reference object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the image reference"
          },
          "weight": {
            "type": "number",
            "description": "The weight of the image reference"
          }
        }
      },
      "ImageIdentity": {
        "type": "object",
        "description": "The image identity object",
        "properties": {
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "The URLs of the image identity"
          }
        }
      },
      "ModifyImageRef": {
        "type": "object",
        "description": "The modify image reference object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the image reference"
          },
          "weight": {
            "type": "number",
            "description": "The weight of the modify image reference"
          }
        }
      },
      "ImageModel": {
        "type": "string",
        "enum": [
          "photon-1",
          "photon-flash-1"
        ],
        "default": "photon-1",
        "description": "The image model used for the generation"
      },
      "ImageFormat": {
        "type": "string",
        "enum": [
          "jpg",
          "png"
        ],
        "default": "jpg",
        "description": "The format of the image"
      },
      "ImageGenerationRequest": {
        "type": "object",
        "description": "The image generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "image"
            ],
            "default": "image"
          },
          "model": {
            "$ref": "#/components/schemas/ImageModel",
            "description": "The model used for the generation"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt of the generation"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio",
            "description": "The aspect ratio of the generation"
          },
          "format": {
            "$ref": "#/components/schemas/ImageFormat",
            "description": "The format of the image",
            "default": "jpg"
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "The callback URL for the generation"
          },
          "image_ref": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImageRef"
            }
          },
          "style_ref": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImageRef"
            }
          },
          "character_ref": {
            "type": "object",
            "properties": {
              "identity0": {
                "$ref": "#/components/schemas/ImageIdentity"
              }
            }
          },
          "modify_image_ref": {
            "$ref": "#/components/schemas/ModifyImageRef"
          },
          "sync": {
            "type": "boolean",
            "description": "Create image in synchronous mode and return complated image",
            "default": false
          },
          "sync_timeout": {
            "type": "number",
            "description": "The timeout for the synchronous image generation",
            "default": 60
          }
        },
        "required": [
          "model"
        ]
      },
      "UpscaleVideoGenerationRequest": {
        "type": "object",
        "description": "The upscale generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "upscale_video"
            ],
            "default": "upscale_video"
          },
          "resolution": {
            "$ref": "#/components/schemas/VideoModelOutputResolution",
            "description": "The resolution of the upscale"
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "The callback URL for the upscale"
          }
        }
      },
      "AudioGenerationRequest": {
        "type": "object",
        "description": "The audio generation request object",
        "properties": {
          "generation_type": {
            "type": "string",
            "enum": [
              "add_audio"
            ],
            "default": "add_audio"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt of the audio"
          },
          "negative_prompt": {
            "type": "string",
            "description": "The negative prompt of the audio"
          },
          "callback_url": {
            "type": "string",
            "format": "uri",
            "description": "The callback URL for the audio"
          }
        }
      }
    }
  },
  "paths": {
    "/generations/video": {
      "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"
                }
              }
            }
          }
        }
      }
    }
  }
}
```