Create a MiniMax H3 video

POST

videos

curl \
  https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --form-string 'model=minimax-h3' \
  --form-string 'prompt=A paper boat glides across a still pond, daylight, locked camera, no text.' \
  --form-string 'seconds=5' \
  --form-string 'size=2544x1456'

{
  "id": "<task_id>",
  "task_id": "<task_id>",
  "object": "video",
  "model": "minimax-h3",
  "status": "queued",
  "progress": 0,
  "created_at": 1779938152
}

Create a MiniMax H3 or H3-Max 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 a model

Set model to one of the following model IDs. Choose a request size from the matching model table in Set duration and size.

Model ID	Resolution tiers
`minimax-h3`	`768P`, `2K`
`minimax-h3-max`	`480P`, `768P`

Choose an input mode

Both models use the fields below. Set model to the model ID that you selected.

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

The H3-Max request samples include text-to-video at both resolution tiers, reference images, combined image/video/audio references, and first and last frames.

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. To combine image, video, and audio references, send input_reference, reference_videos, and reference_audios in the same request.

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. With frame inputs, size selects the resolution tier. The service can normalize the final output dimensions based on the supplied 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

For both models, set seconds to an integer from 5 through 15. The default is 5 seconds. Choose a resolution and aspect ratio from the table for your model, then send the corresponding Request size value as size in WxH form. For text and reference-media requests, size selects the resolution tier and framing aspect ratio. The service can normalize the final output dimensions based on the requested size and supplied reference media.

Sizes for `minimax-h3`

Use these request sizes with model=minimax-h3:

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`

Sizes for `minimax-h3-max`

Use these request sizes with model=minimax-h3-max:

Resolution	Aspect ratio	Request size
`480P`	`21:9`	`1120x480`
`480P`	`16:9`	`864x480`
`480P`	`4:3`	`640x480`
`480P`	`1:1`	`480x480`
`480P`	`3:4`	`480x640`
`480P`	`9:16`	`480x864`
`768P`	`21:9`	`1792x768`
`768P`	`16:9`	`1360x768`
`768P`	`4:3`	`1024x768`
`768P`	`1:1`	`768x768`
`768P`	`3:4`	`768x1024`
`768P`	`9:16`	`768x1360`

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

enum<string>

default:minimax-h3

required

Model ID for the video task. Use minimax-h3 for 768P or 2K, or minimax-h3-max for 480P or 768P. Choose size from the matching model table.

Available options:

minimax-h3,

minimax-h3-max

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 size in WxH form. For text and reference-media requests, size selects the resolution tier and framing aspect ratio. With first or last frames, size selects the resolution tier. Use the matching model table: minimax-h3 uses 768P or 2K; minimax-h3-max uses 480P or 768P. For example, use 1344x768 for H3 at 768P, 864x480 for H3-Max at 480P, or 1360x768 for H3-Max at 768P. The service can normalize the final output dimensions.

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

Examples:

"1536x672"

"1344x768"

"1024x768"

"768x768"

"768x1024"

"768x1344"

"2912x1280"

"2544x1456"

"1920x1440"

"1440x1440"

"1440x1920"

"1440x2560"

"1120x480"

"864x480"

"640x480"

"480x480"

"480x640"

"480x864"

"1792x768"

"1360x768"

"768x1360"

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

enum<string>

required

Model ID that the task uses.

Available options:

minimax-h3,

minimax-h3-max

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

Last modified on September 14, 2026

curl \
  https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --form-string 'model=minimax-h3' \
  --form-string 'prompt=A paper boat glides across a still pond, daylight, locked camera, no text.' \
  --form-string 'seconds=5' \
  --form-string 'size=2544x1456'

{
  "id": "<task_id>",
  "task_id": "<task_id>",
  "object": "video",
  "model": "minimax-h3",
  "status": "queued",
  "progress": 0,
  "created_at": 1779938152
}

Content moderation

API keys

Choose a model

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

Sizes for `minimax-h3`

Sizes for `minimax-h3-max`

Task flow

Authorizations

Body

Response

​Choose a model

​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

​Sizes for minimax-h3

​Sizes for minimax-h3-max

​Task flow

Authorizations

Body

Response

Choose a model

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

Sizes for `minimax-h3`

Sizes for `minimax-h3-max`

Task flow