MiniMax Hailuo AI- Text To Video API Docs

The MiniMax Hailuo AI Video API documentation provides comprehensive guidance on effectively using this powerful tool to generate dynamic video content based on simple text prompts. Designed to be user-friendly, the API documentation covers a range of functionalities, offering developers detailed insights into integrating the API into their applications or projects.

Authentication:

To access the MiniMax Hailuo AI text-to-video API, users must subscribe to the service and acquire an Ocp-Apim-Subscription-Key. This key is required 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/minimax-hailuo-ai/v1/generate

Request Body Parameters

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

Parameters Type Required Description
prompt string yes The description or narrative for generating the video content.
prompt_optimizer boolean optional Default is true. Optimizes the prompt for improved video quality.

Example Request Body

JSON

{
    "prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere."
}
    

Request Code

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

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

{
    "prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere."
}
import urllib.request, json

try:
    url = "https://gateway.appypie.com/minimax-hailuo-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 high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere."
};

fetch('https://gateway.appypie.com/minimax-hailuo-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/minimax-hailuo-ai/v1/generate" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"prompt\": \"A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.\"
}"
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/minimax-hailuo-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 high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.\" }".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/minimax-hailuo-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 high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere."
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

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


Response

Upon successful execution, the API responds with a task_id, which is used to check the status and retrieve the generated video.

Example Success Response

JSON

HTTP/1.1 200 OK

{
  "task_id": "11173647XXXXXXXXXX",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
    

Next Step: Fetch the request status and get the result

Video Result Endpoint

https://gateway.appypie.com/minimax-hailuo-ai-polling/v1/getStatus

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/minimax-hailuo-ai-polling/v1/getStatus

Request Body Parameters

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

Parameters Type Required Description
prompt string Yes The description or narrative for generating the video content.
prompt_optimizer boolean optional Default is true. Optimizes the prompt for improved video quality.

Example Request Body

JSON

{
   "task_id": "11173647XXXXXXXXXX"
}           

Request Code

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

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

{
    "task_id": "11173647XXXXXXXXXX"
}
import urllib.request, json

try:
    url = "https://gateway.appypie.com/minimax-hailuo-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": "11173647XXXXXXXXXX"
};

fetch('https://gateway.appypie.com/minimax-hailuo-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/minimax-hailuo-ai-polling/v1/getStatus" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"task_id\": \"11173647XXXXXXXXXX\"
}"
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/minimax-hailuo-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\": \"11173647XXXXXXXXXX\" }".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/minimax-hailuo-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": "11173647XXXXXXXXXX"
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

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


Response

JSON

HTTP/1.1 200 OK
{
    "file": {
        "file_id": 202452863353065,
        "bytes": 0,
        "created_at": 1730984510,
        "filename": "output.mp4",
        "purpose": "video_generation",
        "download_url": "https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/inference_output%2Fvideo%2F2024-11-07%2F95cf3504-d7b7-4805-b79a-3bfc5f362553%2Foutput.mp4?"
    },
    "base_resp": {
        "status_code": 0,
        "status_msg": "success"
    }
}
    

Response Handling

The MiniMax Hailuo AI - Text to Video API returns specific HTTP status codes and response bodies to indicate whether a request has succeeded or failed. Developers should incorporate effective error handling in their applications to manage these responses appropriately.

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

{
    "status": "NOT_FOUND"
}    
    

Conclusion

This documentation provides all the essential information to effectively use the MiniMax Hailuo AI - Text to Video API. It outlines each step required to authenticate, send requests, and retrieve video content based on your text prompts. Ensure that you replace YOUR_SUBSCRIPTION_KEY with the actual subscription key you received when signing up for the service. This key is essential for accessing all the API functionalities, from generating video content to retrieving final video results.