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.
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.
Content-Type | Set to application/json |
---|---|
Cache-Control | Recommended to set to no-cache |
Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Base URL: https://gateway.appypie.com/lumalabs-ai/v1/generate
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. |
JSON
{ "prompt": "A giant floating jellyfish gliding over a city skyline, its tentacles glowing softly in the night.", "aspect_ratio": "16:9", "loop": true }
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);
JSON
HTTP/1.1 200 OK { "requestId": "ID" }
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.
Content-Type | Set to application/json |
---|---|
Cache-Control | Recommended to set to no-cache |
Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Base URL: https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus
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. |
JSON
{ "task_id": "20dd7c76-a931-4ac2-8adb-5c17468bXXXX" }
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);
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" }
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.
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" } |
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." }
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.