Luma Dream Machine (T2V) API Docs

The Luma Dream Machine Video Generation API documentation is a practical guide for developers to create vivid, natural video scenes from text prompts or initial frames. Featuring straightforward endpoints and detailed parameters, it empowers developers to seamlessly integrate high-quality, AI-driven video generation capabilities into any project, enhancing creative possibilities.

Authentication:

Accessing the API requires an active subscription and an Subscription-Key. This key must be included in the request headers to authenticate each API call.

Request Headers:

Content-Type Set to application/json
Cache-Control Recommended to set to no-cache
Ocp-Apim-Subscription-Key YOUR_SUBSCRIPTION_KEY

Endpoint

Base URL: https://gateway.appypie.com/lumalabs-ai/v1/generate

Request Body Parameters

API Parameters: The API POST- https://gateway.appypie.com/lumalabs-ai/v1/generate takes the following parameters:

Parameters Type Required Description
prompt string Required (for text-to-video) The text description for generating the video scene.
aspect_ratio string optional Defines the aspect ratio of the video. If not specified, the default is 16:9. Examples of aspect ratios include 16:9, 4:3, 1:1, 9:16, 3:4, 21:9, 9:21, and more.
loop boolean optional Indicates if the video should loop; defaults to false.

Example Request Body

JSON

{
    "prompt": "A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.",
    "aspect_ratio": "16:9",
    "loop": true
}
    

Request Code

Input
POST https://gateway.appypie.com/lumalabs-ai/v1/generate HTTP/1.1

Content-Type: application/json
Cache-Control: no-cache

{
    "prompt": "A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.",
    "aspect_ratio": "16:9",
    "loop": true
}
import urllib.request, json

try:
    url = "https://gateway.appypie.com/lumalabs-ai/v1/generate"

    hdr ={
    # Request headers
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    }

    # Request body
    data =  
    data = json.dumps(data)
    req = urllib.request.Request(url, headers=hdr, data = bytes(data.encode("utf-8")))

    req.get_method = lambda: 'POST'
    response = urllib.request.urlopen(req)
    print(response.getcode())
    print(response.read())
    except Exception as e:
    print(e)
// Request body
const body = {
    "prompt": "A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.",
    "aspect_ratio": "16:9",
    "loop": true
};

fetch('https://gateway.appypie.com/lumalabs-ai/v1/generate', {
        method: 'POST',
        body: JSON.stringify(body),
        // Request headers
        headers: {
            'Content-Type': 'application/json',
            'Cache-Control': 'no-cache',}
    })
    .then(response => {
        console.log(response.status);
        console.log(response.text());
    })
    .catch(err => console.error(err));
curl -v -X POST "https://gateway.appypie.com/lumalabs-ai/v1/generate" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"prompt\": \"A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.\",
    \"aspect_ratio\": \"16:9\",
    \"loop\": true
}"
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import java.io.UnsupportedEncodingException;
import java.io.DataInputStream;
import java.io.InputStream;
import java.io.FileInputStream;

public class HelloWorld {

  public static void main(String[] args) {
    try {
        String urlString = "https://gateway.appypie.com/lumalabs-ai/v1/generate";
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        //Request headers
    connection.setRequestProperty("Content-Type", "application/json");
    
    connection.setRequestProperty("Cache-Control", "no-cache");
    
        connection.setRequestMethod("POST");

        // Request body
        connection.setDoOutput(true);
        connection
            .getOutputStream()
            .write(
             "{ \"prompt\": \"A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.\", \"aspect_ratio\": \"16:9\", \"loop\": true }".getBytes()
             );
    
        int status = connection.getResponseCode();
        System.out.println(status);

        BufferedReader in = new BufferedReader(
            new InputStreamReader(connection.getInputStream())
        );
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content);

        connection.disconnect();
    } catch (Exception ex) {
      System.out.print("exception:" + ex.getMessage());
    }
  }
}
$url = "https://gateway.appypie.com/lumalabs-ai/v1/generate";
$curl = curl_init($url);

curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

# Request headers
$headers = array(
    'Content-Type: application/json',
    'Cache-Control: no-cache',);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

# Request body
$request_body = '{
    "prompt": "A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.",
    "aspect_ratio": "16:9",
    "loop": true
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

$resp = curl_exec($curl);
curl_close($curl);
var_dump($resp);


Response

JSON

HTTP/1.1 200 OK


{
    "requestId": "ID"
}
    

Next Step: Video Result

Retrieving Video Status and URL

To verify the completion status of your video request and retrieve the video URL, make a follow-up API call using the task_id provided in the initial response.

Request Headers:

Content-Type Set to application/json
Cache-Control Recommended to set to no-cache
Ocp-Apim-Subscription-Key YOUR_SUBSCRIPTION_KEY

Endpoint

Base URL: https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus

Request Body Parameters

API Parameters: The API POST- https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus takes the following parameters:

Parameters Type Required Description
requestId string Yes A unique identifier received from the initial video generation request, used to check the status and retrieve the final video.

Example Request Body

JSON

{
   "task_id": "20dd7c76-a931-4ac2-8adb-5c17468bXXXX"
}          

Request Code

Input
POST https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus HTTP/1.1

Content-Type: application/json
Cache-Control: no-cache

{
    "task_id": "ID"
}

import urllib.request, json

try:
    url = "https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus"

    hdr ={
    # Request headers
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    }

    # Request body
    data =  
    data = json.dumps(data)
    req = urllib.request.Request(url, headers=hdr, data = bytes(data.encode("utf-8")))

    req.get_method = lambda: 'POST'
    response = urllib.request.urlopen(req)
    print(response.getcode())
    print(response.read())
    except Exception as e:
    print(e)
// Request body
const body = {
    "task_id": "ID"
};

fetch('https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus', {
        method: 'POST',
        body: JSON.stringify(body),
        // Request headers
        headers: {
            'Content-Type': 'application/json',
            'Cache-Control': 'no-cache',}
    })
    .then(response => {
        console.log(response.status);
        console.log(response.text());
    })
    .catch(err => console.error(err));
curl -v -X POST "https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"task_id\": \"ID\"
}"
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import java.io.UnsupportedEncodingException;
import java.io.DataInputStream;
import java.io.InputStream;
import java.io.FileInputStream;

public class HelloWorld {

  public static void main(String[] args) {
    try {
        String urlString = "https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus";
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        //Request headers
    connection.setRequestProperty("Content-Type", "application/json");
    
    connection.setRequestProperty("Cache-Control", "no-cache");
    
        connection.setRequestMethod("POST");

        // Request body
        connection.setDoOutput(true);
        connection
            .getOutputStream()
            .write(
             "{ \"task_id\": \"ID\" }".getBytes()
             );
    
        int status = connection.getResponseCode();
        System.out.println(status);

        BufferedReader in = new BufferedReader(
            new InputStreamReader(connection.getInputStream())
        );
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content);

        connection.disconnect();
    } catch (Exception ex) {
      System.out.print("exception:" + ex.getMessage());
    }
  }
}
$url = "https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus";
$curl = curl_init($url);

curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

# Request headers
$headers = array(
    'Content-Type: application/json',
    'Cache-Control: no-cache',);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

# Request body
$request_body = '{
    "task_id": ""
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

$resp = curl_exec($curl);
curl_close($curl);
var_dump($resp);


Response

JSON

HTTP/1.1 200 OK
{
    "status": "completed",
    "video_url": "https://storage.cdn-luma.com/lit_lite_inference_v1.6-xl/fdeef69f-3e12-49c9-96a5-52f1ccbd03a3/94e029b5-bfc3-4bc6-be9a-af8c02861770_video04cce1fe67983466ab5ed1bc91631144c.mp4"
}
    

Response Handling

The Luma Dream Machine API returns specific HTTP status codes and response bodies to indicate the success or failure of a request. Developers should implement robust error handling to manage these responses effectively.

Common Status Codes and Responses

Status Code Description Response Body
200 Success - The request was successfully processed, and the image generation is in progress or completed. { "msg": "Image Getting Created", ... }
400 Bad Request - The request contains invalid parameters or missing fields. { "error": "Invalid request parameters" }
401 Unauthorized - The provided subscription key is missing or invalid. { "error": "Invalid or missing authentication" }
403 Forbidden - The subscription does not have access to this API or action. { "error": "Access denied for this operation" }
404 Not Found - The requested resource or endpoint could not be found. { "error": "Endpoint not found" }
429 Too Many Requests - The request rate limit has been exceeded. { "error": "Rate limit exceeded, please retry later" }
500 Internal Server Error - An unexpected error occurred on the server. { "error": "An unexpected error occurred, please try again later" }

Example Error Response

If a request fails due to an issue such as a missing or invalid resource, the response might look like this:

{
    "status": "NOT_FOUND",
    "error": "The requested resource could not be located."
}    
    

Conclusion

This guide outlines essential details for effectively interacting with the Luma Dream Machine API. By following these practices, developers can ensure smooth integration and handle errors gracefully in their applications. Always replace YOUR_SUBSCRIPTION_KEY with the actual key provided upon subscribing to the service.