Minimax H3 Reference-to-Video

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "minimax-h3-reference-to-video",
  "prompt": "Use the person in Image 1 as the sole character reference, preserving face, hairstyle, and clothing. The character walks into the wind on a seaside boardwalk as the camera tracks smoothly from a medium shot to a side close-up in sunset backlight.",
  "image_urls": [
    "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
  ],
  "duration": 5,
  "quality": "2k",
  "aspect_ratio": "adaptive"
}
'

{
  "created": 1761313744,
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-reference-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": false,
    "estimated_time": 165,
    "video_duration": 8
  },
  "type": "video",
  "usage": {
    "billing_rule": "per_second",
    "credits_reserved": 50,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: minimax-h3-reference-to-video",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

POST

videos

generations

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "minimax-h3-reference-to-video",
  "prompt": "Use the person in Image 1 as the sole character reference, preserving face, hairstyle, and clothing. The character walks into the wind on a seaside boardwalk as the camera tracks smoothly from a medium shot to a side close-up in sunset backlight.",
  "image_urls": [
    "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
  ],
  "duration": 5,
  "quality": "2k",
  "aspect_ratio": "adaptive"
}
'

{
  "created": 1761313744,
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-reference-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": false,
    "estimated_time": 165,
    "video_duration": 8
  },
  "type": "video",
  "usage": {
    "billing_rule": "per_second",
    "credits_reserved": 50,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: minimax-h3-reference-to-video",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

Authorizations

Authorization

string

header

required

##All endpoints require Bearer Token authentication##

Get API Key:

Visit the API Key Management Page to obtain your API Key

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

default:minimax-h3-reference-to-video

required

Video generation model name

Available options:

minimax-h3-reference-to-video

Example:

"minimax-h3-reference-to-video"

prompt

string

required

Describe how the reference assets should be used and the video you want to generate.

Prompt requirements:

Required and cannot be empty
Chinese and English are supported
We recommend no more than 500 Chinese characters or 1000 English words; the model may ignore some details in an overly long prompt

Asset reference rules:

Refer to assets as Image 1, Image 2, Video 1, Audio 1, and so on; do not use Seedance-style @image1 or @video1
Numbering starts at 1 and follows the order within each URL array
The first item in image_urls is Image 1, the first in video_urls is Video 1, and the first in audio_urls is Audio 1

Input restrictions:

image_start and image_end are not supported
Provide at least 1 reference image or 1 reference video; reference audio cannot be used by itself

Minimum string length: 1

Example:

"Replace the person in Video 1 with the character from Image 1, preserving the face, hairstyle, and clothing. Keep the motion, pacing, composition, and camera language of Video 1, and perform the dialogue with the voice from Audio 1 with synchronized lips."

image_urls

string<uri>[]

Array of HTTP(S) reference-image URLs. Defaults to []; maximum 9 images.

Role and numbering:

Every image is used as reference_image
The first item is Image 1, the second is Image 2, and so on

Image requirements:

Formats: JPG, JPEG, PNG, WEBP, HEIC, HEIF
File size: no more than 30MB each
Width and height: each from 256 to 5760 px
Aspect ratio (width/height): 0.4–2.5
URLs must use HTTP(S) and be directly accessible by the service
The complete JSON request body must not exceed 64MB; Base64 and mm_file:// inputs are not accepted

Combination rules:

Provide at least 1 reference image or 1 reference video
Supplying only audio_urls returns a parameter error

Maximum array length: 9

Example:

[
  "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
]

video_urls

string<uri>[]

Array of HTTP(S) reference-video URLs. Defaults to []; maximum 3 videos.

Role and numbering:

Every video is used as reference_video
The first item is Video 1, the second is Video 2, and so on

Video requirements:

Containers: MP4 (.mp4), MOV (.mov)
Video codecs: H.264/AVC, H.265/HEVC
Embedded audio codecs: AAC, MP3
File size: no more than 50MB each
Duration: 2–15 seconds per clip; total reference-video duration no more than 15 seconds
Width and height: each from 256 to 5760 px
Aspect ratio (width/height): 0.4–2.5
Frame rate: 23.976–60 FPS
URLs must use HTTP(S) and be directly accessible by the service
The complete JSON request body must not exceed 64MB; Base64 and mm_file:// inputs are not accepted

Billing:

Reference-video input duration is billable

Combination rules:

Provide at least 1 reference image or 1 reference video
Supplying only audio_urls returns a parameter error

Maximum array length: 3

Example:

[
  "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/297573323635_00_%E8%A7%86%E9%A2%911_YnyRbxEwio_video_20260525_163755_1927e9d3.mp4"
]

audio_urls

string<uri>[]

Array of HTTP(S) reference-audio URLs. Defaults to []; maximum 3 clips.

Role and numbering:

Every audio clip is used as reference_audio
The first item is Audio 1, the second is Audio 2, and so on

Audio requirements:

Formats: WAV, MP3
File size: no more than 15MB each
Duration: 2–15 seconds per clip; total reference-audio duration no more than 15 seconds
URLs must use HTTP(S) and be directly accessible by the service
The complete JSON request body must not exceed 64MB; Base64 and mm_file:// inputs are not accepted

Combination rules:

Reference audio cannot be used by itself
When using audio_urls, also provide at least 1 reference image or 1 reference video

Maximum array length: 3

Example:

[
  "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/f463d523c5ce_01_%E9%9F%B3%E9%A2%911_RSLcbpzJPo_6%E6%9C%885%E6%97%A5(1).mp3"
]

duration

integer

default:5

Output video duration in seconds. Defaults to 5 seconds.

Value restrictions:

Only integers from 5 through 15, inclusive, are supported
Decimals, numeric strings, auto, and -1 are not supported
Output duration directly affects billing

Required range: 5 <= x <= 15

Example:

5

quality

enum<string>

default:2k

Output video resolution. Defaults to 2k.

Available value:

2k: the only resolution currently supported

Notes:

768p is not yet available and returns a parameter error
Output bitrate, frame rate, video codec, and audio codec are selected by the platform and are not configurable

Available options:

2k

Example:

"2k"

aspect_ratio

enum<string>

default:adaptive

Output video aspect ratio. Defaults to adaptive.

Available values:

adaptive: the model selects a suitable ratio from the reference assets and prompt
21:9: ultrawide
16:9: landscape
4:3: standard landscape
1:1: square
3:4: standard portrait
9:16: portrait

Available options:

adaptive,

21:9,

16:9,

4:3,

1:1,

3:4,

9:16

Example:

"adaptive"

callback_url

string<uri>

HTTPS callback URL for task completion

Callback timing:

Triggered when the task is completed or failed
Sent after billing confirmation is complete

Security restrictions:

Only HTTPS protocol is supported
Callbacks to private IP addresses are prohibited (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.)
URL length must not exceed 2048 characters

Callback mechanism:

Timeout: 10 seconds
Up to 3 retries after failure (at 1/2/4 seconds after failure respectively)
Callback response body format is consistent with the task query endpoint response format
A 2xx status code is considered successful; other status codes trigger retries

Pattern: ^https://

Example:

"https://your-domain.com/webhooks/video-task-completed"

Response

Video generation task created successfully

created

integer

Task creation timestamp

Example:

1761313744

string

Task ID

Example:

"task-unified-1774857405-abc123"

model

string

Actual model name used

Example:

"minimax-h3-reference-to-video"

object

enum<string>

Specific type of the task

Available options:

video.generation.task

progress

integer

Task progress percentage (0-100)

Required range: 0 <= x <= 100

Example:

0

status

enum<string>

Task status

Available options:

pending,

processing,

completed,

failed

Example:

"pending"

task_info

object

Video task details

Show child attributes

type

enum<string>

Output type of the task

Available options:

text,

image,

audio,

video

Example:

"video"

usage

object

Usage and billing information

Show child attributes

Minimax H3 Image-to-Video Kling Custom Element

Image Series

Video Series

Audio Series

Text Series

Account Management

Task Management

File Management

Minimax H3 Reference-to-Video

Authorizations

Body

Response