Name: Text-to-Video & Image-to-Video API (MiniMax Hailuo 02)
Brand: magicapi
SKU: api-magicapi-text-to-video-image-to-video-api-minimax-hailuo-02
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 Text-to-Video & Image-to-Video API (MiniMax Hailuo 02)

## Overview
The **Text-to-Video & Image-to-Video API (MiniMax Hailuo 02)** makes short videos with MiniMax's Hailuo 02 model, which MiniMax describes as excelling at real world physics. Describe the scene in a `prompt`, optionally give a first frame image (and a last frame image), and choose the resolution and length. Each request returns a URL to one MP4 video.

## Features
- **Text-to-video:** `prompt` is the only required field.
- **Image-to-video:** pass `first_frame_image` to start the video from your image. The output video has the same aspect ratio as this image.
- **Last frame control:** pass `last_frame_image` and the final frame of the video will match it.
- **Resolution:** `512p` or `768p` (standard), or `1080p` (pro, the default). The model notes that the pro option is not just higher resolution but also higher quality.
- **Duration:** `6` (default) or `10` seconds. The model's schema says 10 seconds is only available at 768p, so 1080p videos are always 6 seconds.
- **Prompt optimizer:** `prompt_optimizer` (default `true`) lets the model optimize your prompt before generation. Set it to `false` to turn this off.

## Use Cases
### Ads and Social Clips
Turn a one-line scene description into a short clip for campaigns and social posts.

### Animating Stills
Start from a product shot, photo or artwork with `first_frame_image` and add motion and camera movement.

### Controlled Transitions
Set both `first_frame_image` and `last_frame_image` to make a clip that moves from one picture to another.

### Storyboards and Previsualization
Draft scenes, camera moves and physical action from written descriptions before a shoot.

## Visual Examples
This is the real request we sent through api.market and the video it produced.

**Prompt used:**
> A red kite rises over green hills on a windy morning, the camera tilts up to follow it into the clouds

**Settings:** `resolution` `768p`, `duration` `6`, all other fields at their defaults (`prompt_optimizer` on, no first or last frame image).

**Output:** [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/hailuo-02-output-api-market.mp4)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.01 per API unit.
- **Billing unit:** each request returns one video. The number of units depends on the `resolution` and `duration`:
  - **512p, 6 seconds:** 13 units = **$0.13 per video**
  - **512p, 10 seconds:** 19 units = **$0.19 per video** (this is the billing rate if the model accepts the combination; its schema says 10 seconds is only available at 768p)
  - **768p, 6 seconds:** 34 units = **$0.34 per video** (the example on this page)
  - **768p, 10 seconds:** 57 units = **$0.57 per video**
  - **1080p, 6 seconds:** 60 units = **$0.60 per video** (the default, since the model defaults to 1080p and 6 seconds)
- 1080p is only available for 6 second videos.
- Using a first or last frame image or the prompt optimizer does not change the price.
- **Failed or cancelled predictions** are not billed.
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation
### Base URL
```
https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02
```

### Authentication
Include your api.market API key in the `x-api-market-key` header of every request:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.
1. Send `POST /predictions` with the model `version` and your `input`. A successful call returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the prediction was accepted; it is not an error.
2. Poll `GET /predictions/{id}` every second or two.
3. Stop when `status` is `succeeded` (the `output` field holds the video URL), `failed` (see the `error` field) or `canceled`.

Video generation takes a while. The code samples below poll once per second and give up after 600 seconds (10 minutes); raise the timeout if your requests take longer.

### Endpoints

#### POST /predictions
Create a prediction. This is the request used for the example on this page:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "baaadb886e09b1e711387e270d841930e8253f08775bc6cb176580658f0f2fd9",
    "input": {
      "prompt": "A red kite rises over green hills on a windy morning, the camera tilts up to follow it into the clouds",
      "resolution": "768p",
      "duration": 6
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "baaadb886e09b1e711387e270d841930e8253f08775bc6cb176580658f0f2fd9",
  "status": "starting",
  "created_at": "2026-10-12T10:42:30.886Z"
}
```

#### GET /predictions/{id}
Check the status of a prediction.
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-02-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-12T10:42:30.886Z",
  "started_at": "2026-10-12T10:42:30.927Z",
  "completed_at": "2026-10-12T10:45:00.886Z"
}
```

`output` is a single URL to the generated video.

### Input Parameters
| Parameter | Type | Default | Allowed values | Required | Description |
|---|---|---|---|---|---|
| `prompt` | string | none | Any text | Yes | Text prompt for generation. |
| `first_frame_image` | string (URI) | none | Image URL | No | First frame image for video generation. The output video will have the same aspect ratio as this image. |
| `last_frame_image` | string (URI) | none | Image URL | No | Last frame image for video generation. The final frame of the output video will match this image. |
| `duration` | integer | `6` | `6`, `10` | No | Duration of the video in seconds. 10 seconds is only available for 768p resolution. |
| `resolution` | string | `1080p` | `512p`, `768p`, `1080p` | No | Standard 512p, 768p, or pro 1080p. The pro option is also higher quality, not just higher resolution. |
| `prompt_optimizer` | boolean | `true` | `true`, `false` | No | Use prompt optimizer. |

### Status Codes
- **201 Created:** Prediction created (POST). This is the normal success response.
- **200 OK:** Prediction details returned (GET).
- **400 Bad Request:** Invalid input, for example a missing `prompt` or an unsupported `resolution` or `duration`.
- **401 Unauthorized:** Missing or invalid API key.
- **404 Not Found:** No prediction with that ID.
- **429 Too Many Requests:** Too many requests in a short time. Wait and retry.
- **500 Internal Server Error:** Server-side error. Retry after a short wait.

### Error Handling
- A 201 response only means the prediction was accepted. Always poll until `status` is `succeeded`, `failed` or `canceled`.
- When `status` is `failed`, read the `error` field, fix the input and send a new request. Failed predictions are not billed.
- For 429 and 5xx responses, retry with exponential backoff.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide
### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02";
const version = "baaadb886e09b1e711387e270d841930e8253f08775bc6cb176580658f0f2fd9";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function generateVideo(input) {
  const createResponse = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version, input })
  });
  if (createResponse.status !== 201 && createResponse.status !== 200) {
    throw new Error(`API error: ${createResponse.status} ${await createResponse.text()}`);
  }
  const { id } = await createResponse.json();

  const deadline = Date.now() + 10 * 60 * 1000;
  while (Date.now() < deadline) {
    const pollResponse = await fetch(`${baseUrl}/predictions/${id}`, {
      headers: { "x-api-market-key": apiKey }
    });
    if (!pollResponse.ok) {
      throw new Error(`API error: ${pollResponse.status} ${await pollResponse.text()}`);
    }
    const prediction = await pollResponse.json();
    if (prediction.status === "succeeded") return prediction.output;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "unknown error"}`);
    }
    await delay(1000);
  }
  throw new Error("Prediction timed out after 10 minutes");
}

generateVideo({
  "prompt": "A red kite rises over green hills on a windy morning, the camera tilts up to follow it into the clouds",
  "resolution": "768p",
  "duration": 6
}).then((url) => console.log("Video:", url));
```

### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02"
VERSION = "baaadb886e09b1e711387e270d841930e8253f08775bc6cb176580658f0f2fd9"

def generate_video(input_data, timeout_seconds=600):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": VERSION, "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    prediction_id = response.json()["id"]

    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        poll = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-key": API_KEY},
        )
        poll.raise_for_status()
        prediction = poll.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error')}")
        time.sleep(1)
    raise TimeoutError("Prediction timed out")

url = generate_video({
  "prompt": "A red kite rises over green hills on a windy morning, the camera tilts up to follow it into the clouds",
  "resolution": "768p",
  "duration": 6
})
print("Video:", url)
```

### cURL
```bash
# Step 1: create the prediction (returns 201 with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "baaadb886e09b1e711387e270d841930e8253f08775bc6cb176580658f0f2fd9",
    "input": {
      "prompt": "A red kite rises over green hills on a windy morning, the camera tilts up to follow it into the clouds",
      "resolution": "768p",
      "duration": 6
    }
  }'

# Step 2: poll with the id from step 1 until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-image-to-video-api-minimax-hailuo-02/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Tips
- Set `resolution` to `768p` explicitly when you want a 10 second video; the default is `1080p`, which is 6 seconds only.
- Draft at `512p` or `768p` and move to `1080p` for the final version.
- Try turning `prompt_optimizer` off if the optimized result drifts from what you described.
- Use a first frame image with the aspect ratio you want, because the output keeps that aspect ratio.

## FAQ
### What does a request cost if I only send a prompt?
The defaults are `1080p` and 6 seconds, which is 60 units ($0.60).

### Can I make a 10 second 1080p video?
No. 1080p is 6 seconds only. The model's schema says 10 seconds is only available at 768p.

### What happens if a prediction fails?
It is not billed. Read the `error` field, fix the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Text-to-video and image-to-video with MiniMax Hailuo 02, optional first and last frames. 6 seconds at up to 1080p or 10 seconds at 768p. From $0.13 per video.