Skip to main content

MiniMax Video Generation API Reference

The MiniMax Video Generation model supports text-to-video, image-to-video (first frame), image-to-video (last frame), image-to-video (first and last frames), and multimodal reference-to-video .

This document applies only to the China (Beijing) region. Use an API key from this region.

Activate the Service

Go to the Alibaba Cloud Model Studio console, search for "MiniMax", find the MiniMax model card, click Enable Now, and confirm the activation and authorization in the pop-up window.

Applicable Scope

To ensure successful API calls, make sure that the model, Endpoint URL, and API Key all belong to the same region. Cross-region calls will fail.

HTTP Call

Since video generation tasks take a long time (typically 1-5 minutes), the API uses asynchronous calls. The entire process includes two core steps: "Create task -> Poll for results", as described below:

Step 1: Create a Task and Obtain the Task ID

Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis Replace {WorkspaceId} with your actual workspace ID.
  • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
  • For guidance for beginners, see Call APIs with Postman or cURL.

Request Parameters

Request Headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request Body
model string (Required)The model name.Valid values:
  • MiniMax/MiniMax-H3
input object (Required)The input information, such as prompts and media assets.

Properties

prompt string (Required)The text prompt that describes the desired elements and visual characteristics for the generated video.Supports both Chinese and English. The length is calculated by character count and must not exceed 7,000 characters. Exceeding this limit will return an error.media array (Optional)This parameter is not required for text-to-video tasks.A list of media assets used to specify image, video, or audio materials.Supported input combinations (corresponding to different generation scenarios):
  • Image-to-video (first frame): 1 first_frame image.
  • Image-to-video (last frame): 1 last_frame image.
  • Image-to-video (first and last frames): 1 first_frame + 1 last_frame image.
  • Multimodal reference-to-video: A combination of reference images (image_url) + reference videos (feature) + reference audio (driving_audio).
Image-to-video and multimodal reference-to-video are mutually exclusive: when any of image_url / feature / driving_audio types appear in media, first_frame / last_frame cannot be used (and vice versa). The two modes cannot be mixed.

Properties

type string (Required)The media asset type. Valid values:
  • first_frame: First frame image.
  • last_frame: Last frame image.
  • image_url: Reference image (multimodal reference-to-video).
  • feature: Reference video (multimodal reference-to-video).
  • driving_audio: Reference audio (multimodal reference-to-video).
url string (Required)The URL of the media asset. Assets include images, videos, and audio files.

Image input (type=first_frame, last_frame, or image_url)

The image URL.Image requirements:
  • Formats: JPG, JPEG, PNG, WEBP, HEIC, HEIF.
  • Resolution: Width and height must be in the range of [256, 5760] pixels.
  • Aspect ratio (width/height): [0.4, 2.5].
  • File size: Up to 30 MB.
  • Quantity limits: Up to 1 first frame, up to 1 last frame, and up to 9 reference images.

Video input (type=feature)

The video file URL. Used only in multimodal reference-to-video scenarios.Video requirements:
  • Formats: MP4, MOV.
  • Encoding: Video H.264/AVC, H.265/HEVC; Audio AAC, MP3.
  • Duration per clip: [2, 15] seconds; total duration must not exceed 15 seconds.
  • Resolution: Width and height must be in the range of [256, 5760] pixels.
  • Aspect ratio (width/height): [0.4, 2.5].
  • Frame rate: [23.976, 60] fps.
  • File size: Up to 50 MB.
  • Quantity limit: Up to 3 videos.

Audio input (type=driving_audio)

The audio file URL. Used only in multimodal reference-to-video scenarios.Audio requirements:
  • Formats: WAV, MP3.
  • Duration per clip: [2, 15] seconds; total duration must not exceed 15 seconds.
  • File size: Up to 15 MB.
  • Quantity limit: Up to 3 audio files.
parameters object (Optional)Video generation parameters, such as resolution, aspect ratio, and video duration.

Properties

resolution string (Required)The video resolution tier.
  • 768P: Standard resolution.
  • 2K: 2K high-definition resolution.
ratio string (Optional)The aspect ratio of the generated video. Defaults to adaptive (automatic, adaptively selects the most suitable aspect ratio based on input).Valid values:
  • adaptive: Adaptive (default)
  • 16:9
  • 9:16
  • 1:1
  • 4:3
  • 3:4
  • 21:9
Rules for different scenarios:
  • Text-to-video: Required, and must not be adaptive. A specific ratio must be specified.
  • Image-to-video: The aspect ratio is determined by the input image, always adaptive. Other values will not cause an error but will be ignored.
  • Multimodal reference-to-video: Optional, defaults to adaptive. A specific ratio can also be specified.
duration integer (Required)
The duration directly affects the cost. Billing is per second - the longer the duration, the higher the cost. Please check pricing on the Model Studio console.
The duration of the generated video in seconds. Must be an integer in the range [4, 15].Example: 5.watermark boolean (Optional)Whether to add a watermark to the generated video. The watermark is located at the bottom-right corner of the video with the fixed text "AI-generated".
  • false: Default. No watermark is added.
  • true: Add a watermark.
# The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your Model Studio workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "MiniMax/MiniMax-H3",
    "input": {
        "prompt": "Epic space opera theatrical trailer: A female captain stands alone before a massive observation window, the last fleet is assembling and jumping away, bright flashes explode, the bridge shakes, and she is left behind."
    },
    "parameters": {
        "resolution": "768P",
        "ratio": "16:9",
        "duration": 5,
        "watermark": true
    }
}'

Response Parameters

output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query Results by Task ID

Beijing region: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Polling recommendation: Video generation typically takes several minutes. We recommend using a polling mechanism with a reasonable query interval (e.g., 15 seconds) to retrieve results.
  • Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
  • task_id validity period: 24 hours. After expiration, the results cannot be queried, and the API will return a task status of UNKNOWN.
  • RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend Configure asynchronous task callbacks.
  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request Parameters

Request Headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL Path Parameters
task_id string (Required)The ID of the task.
  • Query Task Result
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response Parameters

outputobjectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING → RUNNING → SUCCEEDED or FAILED.
  • The initial query status is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry the task.
submit_time stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.video_urlstringThe video URL. Only returned when task_status is SUCCEEDED.The video format is MP4 (H.264 encoding). The video URL is valid for 30 days, but it is not recommended to rely on it for long-term storage. Please download it promptly.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectOutput statistics. Only counts successful results.

Properties

duration integerThe total billable seconds, equal to input_seconds + output_seconds.size stringThe resolution of the generated video. Example: 1344*768.SR stringThe resolution tier of the generated video. Example: 768.video_count integerThe number of generated videos. Fixed at 1.image_count integerThe billable image count. The first 5 input images are free (returns 0). When more than 5 images are provided, returns the excess count (e.g., 7 images returns 2, i.e., 7-5=2).input_seconds integerThe total duration of input reference videos in seconds. The millisecond-level durations of all input videos are summed and then rounded to the nearest integer. 0 when no reference video is used.output_seconds integerThe total duration of the output video in seconds.total_seconds integerThe total seconds, equal to input_seconds + output_seconds.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task Succeeded
  • Task Failed
  • Task Query Expired
{
    "request_id": "bde5ed1a-86de-9fac-xxxx-xxxxxxxxxxxx",
    "output": {
        "task_id": "ca7eaceb-2b00-4f29-xxxx-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-20 13:54:07.204",
        "scheduled_time": "2026-08-20 13:54:07.249",
        "end_time": "2026-08-20 13:55:58.633",
        "video_url": "https://xxx.oss-cn-shanghai.aliyuncs.com/xxx/output.mp4?Expires=xxx&Signature=YOUR_SIGNATURE"
    },
    "usage": {
        "SR": "768",
        "duration": 5,
        "image_count": 0,
        "input_seconds": 0,
        "output_seconds": 5,
        "size": "1344*768",
        "total_seconds": 5,
        "video_count": 1
    }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
API Usage
Text Generation
Image Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More