Luma Ray 1.6 (Text-to-Video)

This documentation is valid for the following list of our models:

luma/ray-1-6

Try in Playground

Overview

The Luma AI Dream Machine API allows developers to generate and extend AI-generated videos based on text prompts.

Setup your API Key

If you don’t have an API key for the AI/ML API yet, feel free to use our Quickstart guide.

How to Make a Call

Step-by-Step Instructions

Generating a video using this model involves making two sequential API calls:

The first one is for creating and sending a video generation task to the server (returns a generation ID). This can be either a generation from a reference image/prompt or a video extension operation that adds length to an existing video.
The second one is for requesting the generated or extended video from the server using the generation ID received from the first endpoint. Within this API call, you can use either the standard endpoint to retrieve the generated/extended video or a special endpoint to request multiple generations at once.

Below, you can find three corresponding API schemas and examples for all endpoint calls.

API Schemas

Generate video

loop parameter controls if the generated video will be looped.

post

Body

modelstring · enumRequiredPossible values:

promptstringRequired

The text description of the scene, subject, or action to generate in the video.

aspect_ratiostring · enumOptional

The aspect ratio of the generated video.

Default: 16:9Possible values:

loopbooleanOptional

Whether to loop the video

Default: false

Responses

200Success

application/json

post

/v2/video/generations

curl -L \
  --request POST \
  --url 'https://api.aimlapi.com/v2/video/generations' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
      "model": "luma/ray-1-6",
      "prompt": "A menacing evil dragon appears in a distance above the tallest mountain, then rushes toward the camera with its jaws open, revealing massive fangs. We see it’s coming."
    }'

200Success

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000
    }
  }
}

Fetch generation

After sending a request for video generation, this task is added to the queue. This endpoint lets you check the status of a video generation task using its id, obtained from the endpoint described above. If the video generation task status is completed, the response will include the final result — with the generated video URL and additional metadata.

get

Authorizations

AuthorizationstringRequired

Bearer key

Query parameters

generation_idstringRequiredExample: <REPLACE_WITH_YOUR_GENERATION_ID>

Responses

200Success

application/json

get

/v2/video/generations

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/video/generations?generation_id=<REPLACE_WITH_YOUR_GENERATION_ID>' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000
    }
  }
}

Example: Fetch Single Generation

For example, if you are waiting for video dreaming (when the video is popped from the queue and generation is in processing), then you can send the following request:

import requests


def main():
    response = requests.get(
        "https://api.aimlapi.com/v2/generate/video/luma-ai/generation",
        params={
            "generation_id": "755f9bbb-d99b-4880-992b-f05244ddba61",
            "status": "dreaming"
        },
        headers={
            "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
            "Content-Type": "application/json",
        },
    )

    response.raise_for_status()
    data = response.json()
    print("Generation:", data)


if __name__ == "__main__":
    main()

const main = async () => {
  const url = new URL('https://api.aimlapi.com/v2/generate/video/luma-ai/generation');
  url.searchParams.set('generation_id', '755f9bbb-d99b-4880-992b-f05244ddba61');
  url.searchParams.set('state', 'dreaming');

  const data = await fetch(url, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
  }).then((res) => res.json());

  console.log('Generation:', data);
};

main();

Fetch Multiple Generations

Instead of using the generation_id parameter, you will pass generation_ids, which can be an array of IDs. This parameter can also accept IDs separated by commas.

get

Authorizations

AuthorizationstringRequired

Bearer key

Query parameters

generation_idsany ofRequired

string · uuid[] · min: 1Optional

stringOptional

statusstringOptional

Responses

200Success

No content

get

/v2/generate/video/luma-ai/generations

GET /v2/generate/video/luma-ai/generations?generation_ids=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

No content

Example: Fetch Multiple Generations

import requests


def main():
    response = requests.get(
        "https://api.aimlapi.com/v2/generate/video/luma-ai/generations",
        params={
            "generation_ids[]": "755f9bbb-d99b-4880-992b-f05244ddba61",
            "status": "streaming",
        },
        headers={
            "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
            "Content-Type": "application/json",
        },
    )

    response.raise_for_status()
    data = response.json()
    print("Generation:", data)


if __name__ == "__main__":
    main()

const main = async () => {
  const url = new URL('https://api.aimlapi.com/v2/generate/video/luma-ai/generations');
  url.searchParams.set('generation_ids[]', '755f9bbb-d99b-4880-992b-f05244ddba61');
  url.searchParams.set('state', 'dreaming');

  const data = await fetch(url, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
  }).then((res) => res.json());

  console.log('Generation:', data);
};

main();

Example: Fetch Multiple Generations

Ensure you replace <YOUR_AIMLAPI_KEY> with your actual API key before running the code.

import requests


def main():
  url = "https://api.aimlapi.com/v2/generate/video/luma-ai/generation"
  payload = {
    "prompt": "Flying jellyfish",
    "aspect_ratio": "16:9"
  }
  headers = {
    "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
    "Content-Type": "application/json"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  print("Generation:",  response.json())
  
if __name__ == "__main__":
    main()

const main = async () => {
  const response = await fetch('https://api.aimlapi.com/v2/generate/video/luma-ai/generation', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'A jellyfish in the ocean',
      aspect_ratio: '19:9',
      loop: false
    }),
  }).then((res) => res.json());

  console.log('Generation:', response);
};

main();

Extend video

You can extend a video using an existing video you generated before (using its generation ID) or by using an image (via URL). The extension can be done by appending to or prepending from the original content.

The keywords parameter controls the following extensions. It can include parameters for defining frames:

first frame (frame0)
last frame (frame1)

For example, if you want to use an image as a reference for a frame:

{
        "keyframes": {
            "frame0": {
                "type": "image",
                "url": "https://example.com/image1.png"
            }
        }
}

Or, in the case of using a previously generated video:

{
    "keyframes": {
        "frame1": {
            "type": "generation",
            "id": "0f3ea4aa-10e7-4dae-af0b-263ab4ac45f9"
        }
    }
}

post

Authorizations

AuthorizationstringRequired

Bearer key

Body

generation_typestring · enum | nullableOptionalPossible values:

promptstringRequired

aspect_ratiostring · enumOptionalPossible values:

loopbooleanOptionalDefault: false

callback_urlstring · uri | nullableOptional

modelstring · enumOptionalDefault: ray-2Possible values:

resolutionstring · enum | nullableOptionalPossible values:

durationstring · enum | nullableOptionalPossible values:

Responses

201Success

post

/v2/generate/video/luma-ai/generation

POST /v2/generate/video/luma-ai/generation HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 330

{
  "generation_type": "video",
  "prompt": "text",
  "aspect_ratio": "1:1",
  "loop": false,
  "keyframes": {
    "frame0": {
      "type": "generation",
      "id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "frame1": {
      "type": "generation",
      "id": "123e4567-e89b-12d3-a456-426614174000"
    }
  },
  "callback_url": "https://example.com",
  "model": "ray-2",
  "resolution": "540p",
  "duration": "5s"
}

201Success

No content

Examples

Ensure you replace <YOUR_AIMLAPI_KEY> with your actual API key before running the code.

Extension with the Image

import requests


def main()
  url = "https://api.aimlapi.com/v2/generate/video/luma-ai/generation"
  headers = {
    "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
    "Content-Type": "application/json"
  }
  payload = {
    "prompt": "Flying jellyfish",
    "aspect_ratio": "16:9",
    "keyframes": {
      "frame0": {
        "type": "image",
        "url": "https://example.com/image1.png"
      }
    }
  }
  
  response = requests.post(url, json=payload, headers=headers)
  print("Generation:",  response.json())
  
  
if __name__ == "__main__":
    main()

const main = async () => {
  const response = await fetch('https://api.aimlapi.com/v2/generate/video/luma-ai/generation', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'A jellyfish in the ocean',
      aspect_ratio: '19:9',
      keyframes: {
        frame0: {
          type: 'image',
          url: 'https://example.com/image1.png',
        },
      },
    }),
  }).then((res) => res.json());

  console.log('Generation:', response);
};

main();

Extension with the Generation

import requests


def main()
  url = "https://api.aimlapi.com/v2/generate/video/luma-ai/generation"
  headers = {
    "Authorization": "Bearer <YOUR_AIMLAPI_KEY>",
    "Content-Type": "application/json"
  }
  payload = {
    "prompt": "Flying jellyfish",
    "aspect_ratio": "16:9",
    "keyframes": {
      "frame0": {
        "type": "generation",
        "id": "0f3ea4aa-10e7-4dae-af0b-263ab4ac45f9"
      }
    }
  }
  
  response = requests.post(url, json=payload, headers=headers)
  print("Generation:",  response.json())
  
if __name__ == "__main__":
    main()

const main = async () => {
  const response = await fetch('https://api.aimlapi.com/v2/generate/video/luma-ai/generation', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <YOUR_AIMLAPI_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'A jellyfish in the ocean',
      aspect_ratio: '19:9',
      keyframes: {
        frame0: {
          type: 'generation',
          id: '0f3ea4aa-10e7-4dae-af0b-263ab4ac45f9',
        },
      },
    }),
  }).then((res) => res.json());

  console.log('Generation:', response);
};

main();

PreviousLuma 1 (Text-to-Video) [legacy]NextLuma Ray 2

Last updated 14 days ago

Was this helpful?

hashtagOverview

hashtagSetup your API Key

hashtagHow to Make a Call

hashtagAPI Schemas

hashtagGenerate video

hashtagFetch generation

hashtagExample: Fetch Single Generation

hashtagFetch Multiple Generations

hashtagExample: Fetch Multiple Generations

hashtagExample: Fetch Multiple Generations

hashtagExtend video

hashtagExamples

hashtagExtension with the Image

hashtagExtension with the Generation

Overview

Setup your API Key

How to Make a Call

API Schemas

Generate video

Fetch generation

Example: Fetch Single Generation

Fetch Multiple Generations

Example: Fetch Multiple Generations

Example: Fetch Multiple Generations

Extend video

Examples

Extension with the Image

Extension with the Generation