Luma Dream Machine Image to Video API Docs

The Dream Machine Video Generation API Documentation provides developers with detailed instructions for integrating and using the API to transform static images into high-quality videos. The documentation covers all essential aspects, including authentication, request parameters, and handling responses.

Authentication:

To access this API, you must subscribe to the service and obtain a Subscription-Key. This key must be included in the request headers to authenticate your API calls.

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/generateRequestFromImage

Request Body Parameters

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

Parameters Type Required Description
prompt string Yes The narrative or scene description that influences video generation.
url string Yes The URL of the static image used as the starting frame for the video.

Example Request Body

JSON

{
    "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg",
    "prompt": "leaning girl"
}
    

Request Code

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

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

{
    "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg",
    "prompt": "leaning girl"
}
import urllib.request, json

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

    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 = {
    "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg",
    "prompt": "leaning girl"
};

fetch('https://gateway.appypie.com/lumalabs-ai/v1/generateRequestFromImage', {
        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/generateRequestFromImage" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"url\": \"https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg\",
    \"prompt\": \"leaning girl\"
}"
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/generateRequestFromImage";
        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(
             "{ \"url\": \"https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg\", \"prompt\": \"leaning girl\" }".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/generateRequestFromImage";
$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 = '{
    "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg",
    "prompt": "leaning girl"
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

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


Response

JSON

HTTP/1.1 200 OK

{
    "id": "f25c04db-19f7-4b51-871c-af6ed0b32f55",
    "generation_type": "video",
    "state": "queued",
    "failure_reason": null,
    "created_at": "2024-12-06T15:00:46.232527Z",
    "assets": null,
    "model": "ray-1-6",
    "request": {
        "generation_type": "video",
        "prompt": "leaning girl",
        "aspect_ratio": "16:9",
        "loop": false,
        "keyframes": {
            "frame0": {
                "type": "image",
                "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg"
            },
            "frame1": null
        },
        "callback_url": null
    }
}
    

Next Step: Polling Results

Retrieving Video Status and URL

To verify the status of your image generation request and retrieve the image URL, make a subsequent API call using the ID provided in the original response.

Polling Endpoint

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

Request Headers:

Content-Type Set to application/json
Cache-Control Recommended to set to no-cache

Request Body Parameters

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

Request Body

Pass the id received from the initial response in your request body.

Example Request Body

JSON

{
    "task_id":"f25c04db-19f7-4b51-871c-af6ed0b32f55"
}        

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\": \"\"
}"
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": "ID"
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

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


Response for Polling

Upon successful polling, the API returns the video generation status and, if completed, includes the URL of the generated video.

Example Success Response

JSON

{
        "id": "f25c04db-19f7-4b51-871c-af6ed0b3XXXX",
        "generation_type": "video",
        "state": "completed",
        "failure_reason": null,
        "created_at": "2024-12-06T15:00:46.232000Z",
        "assets": {
            "video": "https://storage.cdn-luma.com/dream_machine/29a0547c-674c-4616-ada7-031e67edf924/7785ccf3-a9a3-4831-9c16-1158e317d61b_video0881f13ea6a1e4facbef70182188ea534.mp4",
            "image": "https://storage.cdn-luma.com/dream_machine/29a0547c-674c-4616-ada7-031e67edf924/22d44709-77a6-42d8-bf67-af1e87019236_video_0_thumb.jpg"
        },
        "model": "ray-1-6",
        "request": {
            "generation_type": "video",
            "prompt": "leaning girl",
            "aspect_ratio": "16:9",
            "loop": false,
            "keyframes": {
                "frame0": {
                    "type": "image",
                    "url": "https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg"
                },
                "frame1": null
            },
            "callback_url": null
        }
}
    

Response Handling

The Luma Dream Machine Image-to-Video Generation API provides specific HTTP status codes and detailed response bodies to indicate the outcome of each request. Developers are encouraged to implement effective error handling to process these responses accurately, ensuring a smooth and seamless user experience. Proper error management will help in troubleshooting issues and optimizing the video generation process.

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

{
        "task_status": "failed",
        "task_status_msg": "task not found"
}
    

Conclusion

This detailed documentation offers all the necessary information for effectively using the Luma Dream Machine Image-to-Video Generation API. It includes step-by-step integration instructions and usage guidelines to help you get started. Remember to replace YOUR_SUBSCRIPTION_KEY with your actual key, which is essential for authentication and access. By following the instructions provided, you can easily integrate the API into your applications and fully leverage its capabilities to transform static images into dynamic, high-quality videos.