Create a MiniMax H3 video

Create a MiniMax H3 video from text, reference media, or first and last frames. Store the returned id to poll the task and download the completed video. POST /v1/videos uses multipart/form-data. Send controls as form fields and repeat each reference field once per media input.

Choose an input mode

Goal	Required fields	Optional fields
Text-to-video	`model=minimax-h3`, `prompt`	`seconds`, `size`
Reference images	`model=minimax-h3`, `prompt`, one or more `input_reference` URLs or files	`seconds`, `size`
Reference video URL, data URI, or file	`model=minimax-h3`, `prompt`, one or more `reference_videos` fields	`seconds`, `size`
Reference audio with an image	`model=minimax-h3`, `prompt`, `input_reference`, one or more `reference_audios` fields	`seconds`, `size`
First and last frame URLs	`model=minimax-h3`, `prompt`, `first_frame`	`last_frame`, `seconds`, `size`
Uploaded first and last frames	`model=minimax-h3`, `prompt`, `first_frame` file	`last_frame` file, `seconds`, `size`

Use reference images

Send reference images through input_reference as publicly accessible HTTPS URLs or uploaded files. For multiple images, repeat the field in image order, with one URL or file per field. Use all URLs or all files within this field. Send each URL separately rather than combining URLs into a comma-separated value. You can send up to nine PNG or JPEG reference images, whether you use URLs or uploaded files. Keep each uploaded image at or below 20 MiB. In the prompt, describe the visual details that the generated video should preserve.

Use reference video and audio

Send reference_videos and reference_audios as multipart text values or uploaded files, using the formats below. Repeat each field once per input, using only text values or only files within that field. Do not combine inputs into a comma-separated value. Different fields can use different input types, such as an image URL with an uploaded audio file.

Field	Input	Format
`reference_videos`	A direct, publicly accessible HTTPS MP4 URL or an uploaded MP4 file	MP4 with H.264 video; an AAC audio track is optional
`reference_videos`	A complete Base64 data URI in a text field	`data:video/mp4;base64,<BASE64_MP4>`
`reference_audios`	A direct, publicly accessible HTTPS MP3 URL or an uploaded MP3 file	MP3

Send at most 12 reference inputs in total, including no more than three videos and three audio clips. Each video or audio clip must be 2–15 seconds. The combined video duration and combined audio duration must each be at or below 15 seconds. Pair reference audio with at least one image through input_reference. Describe the motion, timing, or sound that the generated video should follow. Keep each uploaded MP4 at or below 50 MiB and each uploaded MP3 at or below 15 MiB. One MiB is 1024 × 1024 bytes. The request samples at the top of this page show MP4 URLs, MP4 data URIs, and MP3 URLs paired with an image.

Upload a reference video

Upload an MP4 file to guide the shot structure and motion:

curl \
  https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --form-string 'model=minimax-h3' \
  --form-string 'prompt=Follow the uploaded reference video shot structure and motion. No text.' \
  --form-string 'seconds=5' \
  --form-string 'size=1344x768' \
  --form 'reference_videos=@/path/to/reference.mp4;type=video/mp4'

Upload reference audio with an image

Pair a reference image URL with an uploaded MP3 file:

curl \
  https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --form-string 'model=minimax-h3' \
  --form-string 'prompt=Animate the reference image and synchronize the motion with the uploaded reference audio. No text.' \
  --form-string 'seconds=5' \
  --form-string 'size=1344x768' \
  --form-string 'input_reference=https://your-image-host/reference.png' \
  --form 'reference_audios=@/path/to/reference.mp3;type=audio/mpeg'

Set the first and last frames

Send first_frame for the opening image and optionally one last_frame for the ending image. Each field accepts one direct, publicly accessible HTTPS PNG URL or one uploaded PNG file. Keep each uploaded PNG at or below 20 MiB (20 × 1024 × 1024 bytes). Do not combine frame fields with reference image, video, or audio fields. Use a separate request for frame-based generation. The service can normalize the final output dimensions when you provide first or last frames. Continue to send size in WxH form.

Store the returned id. Poll the task until status is completed or failed. When the task is completed, download the video content.

Set duration and size

Set seconds to an integer from 5 through 15. The default is 5 seconds. Choose a resolution and aspect ratio from the table, then send the corresponding Request size value as size in WxH form. The service can normalize the final output dimensions based on the requested size and supplied reference media.

Resolution	Aspect ratio	Request size
`768P`	`21:9`	`1536x672`
`768P`	`16:9`	`1344x768`
`768P`	`4:3`	`1024x768`
`768P`	`1:1`	`768x768`
`768P`	`3:4`	`768x1024`
`768P`	`9:16`	`768x1344`
`2K`	`21:9`	`2912x1280`
`2K`	`16:9`	`2544x1456`
`2K`	`4:3`	`1920x1440`
`2K`	`1:1`	`1440x1440`
`2K`	`3:4`	`1440x1920`
`2K`	`9:16`	`1440x2560`

Task flow

Create the task

Send the multipart form request and store the returned id.

Poll the task

Call Retrieve a MiniMax H3 video until status is completed or failed.

Download the result

When the task is completed, call Download MiniMax H3 video content to save the MP4 file.

Authorizations

Authorization

string

header

required

Bearer authentication. Use your CometAPI API key.

Body

multipart/form-data

model

string

default:minimax-h3

required

Model ID for this route. Use minimax-h3.

Allowed value: "minimax-h3"

prompt

string

default:A paper boat glides across a still pond, daylight, locked camera, no text.

required

Text that describes the scene, motion, camera behavior, and visual details that the video should preserve.

Minimum string length: 1

seconds

integer

default:5

Requested clip duration in whole seconds. Use an integer from 5 through 15. The default is 5.

Required range: 5 <= x <= 15

size

string

Requested frame size in WxH form. The service can normalize the final output dimensions based on the requested size and supplied reference media.

Pattern: ^[1-9][0-9]*x[1-9][0-9]*$

Examples:

"1536x672"

"1344x768"

"1024x768"

"768x768"

"768x1024"

"768x1344"

"2912x1280"

"2544x1456"

"1920x1440"

"1440x1440"

"1440x1920"

"1440x2560"

input_reference

PNG or JPEG reference images. Repeat input_reference with one publicly accessible HTTPS image URL or uploaded image file per field. Send up to nine reference images, whether you use URLs or uploaded files. Use all URLs or all files within this field. Do not combine URLs into a comma-separated value. Keep each uploaded image at or below 20 MiB. Do not combine this field with first_frame or last_frame. Across images, videos, and audio, send at most 12 reference inputs. Each reference video or audio clip must be 2–15 seconds; keep the combined video duration and combined audio duration at or below 15 seconds each. Submit images in the order you want to reference them in the prompt.

Pattern: ^https://

reference_videos

(string<uri> | file)[]

Reference video inputs. Repeat reference_videos with a direct publicly accessible HTTPS MP4 URL or an uploaded MP4 file. Use only text values or only files within this field. Each uploaded file can be up to 50 MiB. Send no more than three video inputs. A complete data:video/mp4;base64,... URI is also accepted as a text value. Use MP4 with H.264 video; an AAC audio track is optional. Do not combine this field with first_frame or last_frame. Across images, videos, and audio, send at most 12 reference inputs. Each reference video or audio clip must be 2–15 seconds; keep the combined video duration and combined audio duration at or below 15 seconds each.

Required array length: 1 - 3 elements

Pattern: ^(https://|data:video/mp4;base64,)

Example:

"https://your-media-host/reference.mp4"

reference_audios

(string<uri> | file)[]

Reference audio inputs. Repeat reference_audios with a direct publicly accessible HTTPS MP3 URL or an uploaded MP3 file. Use only text values or only files within this field. Each uploaded file can be up to 15 MiB. Send no more than three audio inputs. Pair reference audio with at least one reference image. Do not combine this field with first_frame or last_frame. Across images, videos, and audio, send at most 12 reference inputs. Each reference video or audio clip must be 2–15 seconds; keep the combined video duration and combined audio duration at or below 15 seconds each.

Required array length: 1 - 3 elements

Pattern: ^https://

Example:

"https://your-media-host/reference.mp3"

first_frame

Opening frame input as one direct publicly accessible HTTPS PNG URL or one uploaded PNG file at or below 20 MiB (20 x 1024 x 1024 bytes). Do not combine frame fields with reference media fields.

Pattern: ^https://

Example:

"https://your-image-host/first-frame.png"

last_frame

Optional ending frame input, used with first_frame, as one direct publicly accessible HTTPS PNG URL or one uploaded PNG file at or below 20 MiB (20 x 1024 x 1024 bytes). Do not combine frame fields with reference media fields.

Pattern: ^https://

Example:

"https://your-image-host/last-frame.png"

Response

200 - application/json

Task created. Store the returned id and use it in retrieve and content requests.

string

required

Task ID. Use this value as task_id in retrieve and content requests.

Example:

"<task_id>"

object

string

required

Object type for the asynchronous video task.

Allowed value: "video"

model

string

required

Model ID that the task uses.

Allowed value: "minimax-h3"

status

enum<string>

required

Task lifecycle status. Poll until the value is completed or failed.

Available options:

queued,

in_progress,

completed,

failed

progress

integer

required

Task progress as a coarse percentage.

Required range: 0 <= x <= 100

created_at

integer<int64>

required

Task creation time as a Unix timestamp in seconds.

task_id

string

Compatibility alias for id. This field can be omitted from retrieve responses.

Example:

"<task_id>"

completed_at

integer<int64>

Unix timestamp returned by the platform. Use status, not this field, to decide when polling can stop.

expires_at

integer<int64>

Result expiration time as a Unix timestamp in seconds when the task provides one.

video_url

string<uri>

Video delivery URL. This field appears on completed tasks.

Example:

"https://your-media-host/result.mp4"

error

object

Failure details. This field appears when the task fails.

Show child attributes

Content moderation

API keys

Choose an input mode

Use reference images

Use reference video and audio

Upload a reference video

Upload reference audio with an image

Set the first and last frames

Set duration and size

Task flow

Authorizations

Body

Response

​Choose an input mode

​Use reference images

​Use reference video and audio

​Upload a reference video

​Upload reference audio with an image

​Set the first and last frames

​Set duration and size

​Task flow

Authorizations

Body

Response

Choose an input mode

Use reference images

Use reference video and audio

Upload a reference video

Upload reference audio with an image

Set the first and last frames

Set duration and size

Task flow