# MiniMax/Hailuo-2.3-I2V

Image-to-Video Model

## Submit Task (Asynchronous)

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/submit`

### Input

| Parameter                     | Type    | Required | Description |
| :--------------------------- | :------ | :------- | :---------- |
| model                        | string  | Yes      | Model name, here it is `MiniMax-Hailuo-2.3` |
| input.first_frame_image      | string  | Yes      | First frame image of the video. Supports public URL or Base64 Data URL (format: `data:image/jpeg;base64,...`)<br>Image requirements:<br>- Format: JPG, JPEG, PNG, WebP<br>- Size: ≤20MB<br>- Dimensions: shorter side >300px, aspect ratio between 2:5 and 5:2 |
| input.prompt                 | string  | Yes      | Text description for the video, maximum length 2000 characters<br>Supports camera movement instructions, see “Camera Movement Control” |
| parameters.duration          | int     | No       | Video duration (seconds), depends on model and resolution. See “Duration and Resolution Mapping”. Default is `6` |
| parameters.resolution        | string  | No       | Video resolution, depends on model and duration. See “Duration and Resolution Mapping” |
| parameters.prompt_optimizer  | boolean | No       | Whether to automatically optimize the text prompt. Default is `true` |
| parameters.fast_pretreatment | boolean | No       | Whether to shorten prompt optimization time (only effective for MiniMax-Hailuo-2.3). Default is `false` |
| parameters.aigc_watermark    | boolean | No       | Whether to add a watermark to the video. Default is `false` |

### Camera Movement Control

The MiniMax-Hailuo-2.3 series supports camera movement instructions, which can be used in `input.prompt`:

#### Supported Camera Instructions (15 types)

| Category   | Instruction |
| :--------- | :---------- |
| Pan Left/Right | [左移], [右移] |
| Pan Rotation | [左摇], [右摇] |
| Push/Pull | [推进], [拉远] |
| Lift | [上升], [下降] |
| Tilt | [上摇], [下摇] |
| Zoom | [变焦推近], [变焦拉远] |
| Others | [晃动], [跟随], [固定] |

#### Usage Rules

1. **Combined Movements**: Multiple instructions can be added within the same `[]` (recommended ≤3), and will take effect simultaneously. Example: `"prompt": "A cat runs on the grass [左摇,上升]"`
2. **Sequential Movements**: Instructions in the prompt take effect in order. Example: `"prompt": "A cat runs on the grass [推进], then [拉远]"`
3. **Natural Language Support**: Camera movements can also be described in natural language, but standard instructions are more precise

### Duration and Resolution Mapping

#### 1. Supported Durations (seconds) by Model

| Model                  | 720P Resolution | 768P Resolution | 1080P Resolution |
| :--------------------- | :-------------- | :-------------- | :--------------- |
| MiniMax-Hailuo-2.3     | -               | 6, 10           | 6                |

#### 2. Supported Resolutions by Duration

| Model                  | 6s Duration           | 10s Duration      |
| :--------------------- | :-------------------- | :---------------- |
| MiniMax-Hailuo-2.3     | 768P (default), 1080P | 768P (default)    |

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API tools.

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "MiniMax-Hailuo-2.3",
    "input": {
      "first_frame_image": "https://cdn.ucloud.com/prod/2024-09-18-16/user/multi_chat_file/9c0b5c14-ee88-4a5b-b503-4f626f018639.jpeg",
      "prompt": "A mouse runs toward the camera, smiling and blinking. [推进, 跟随]"
    },
    "parameters": {
      "duration": 6,
      "resolution": "1080P",
      "prompt_optimizer": true,
      "fast_pretreatment": false,
      "aigc_watermark": false
    }
  }'
```

### Output

| Parameter      | Type   | Description                         |
| :------------- | :----- | :---------------------------------- |
| output.task_id | string | Unique identifier of the async task |
| request_id     | string | Unique identifier of the request    |

### Response Example

```json
{
  "output": {
    "task_id": "106916112212032"
  },
  "request_id": "request_id"
}
```

## Query Task Status

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>`

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'
```

### Output

| Parameter            | Type    | Description                                             |
| :------------------- | :------ | :------------------------------------------------------ |
| output.task_id       | string  | Unique identifier of the async task                     |
| output.task_status   | string  | Task status: `Pending`, `Running`, `Success`, `Failure` |
| output.urls          | array   | List of video result URLs                               |
| output.submit_time   | integer | Task submission timestamp                               |
| output.finish_time   | integer | Task completion timestamp                               |
| output.error_message | string  | Error message returned when failed                      |
| usage.duration       | integer | Video duration (seconds)                                |
| request_id           | string  | Unique identifier of the request                        |

### Response Example (Success)

```json
{
  "output": {
    "task_id": "176843862716480",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx.mp4"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
    "duration": 6
  },
  "request_id": ""
}
```

### Response Example (Failure)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "usage": {
    "duration": 6
  },
  "request_id": ""
}
```