Skip to navigation

MiniMax H3 Normal

Generate 5–15 second videos with sound at 480p, 768p or 1080p from text, one or two frames, or up to 4 images and 1 video as references, about a third below the minimax-h3 rate.

  • Asynchronous: the create call returns a task ID; the video arrives when the task succeeds. Normal renders more slowly than Fast.
  • About a third below the minimax-h3 rate at 768p, with 480p and 1080p besides 768p.
  • Every video comes with generated sound; there is no field to turn it off, and no audio input.
  • Four ways in: text only, a first frame, a first and last frame, or up to 4 reference images and 1 reference video. seed is optional.
  • Billed per second of video. A failed task costs nothing.
POST/v1/videos/tasksTry it

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

Five MiniMax H3 models share this endpoint but not the same inputs. The values below come straight from the gateway contract.

Model IDduration (s)resolutionMax reference imagesMax reference videosMax reference audioChoose it when
minimax-h34–30480p, 768p, 1080p, 2K933You want the standard lane at the lower rate; the inputs are the same as minimax-h3-fast.
minimax-h3-fast4–30480p, 768p, 1080p, 2K933You want the priority lane for faster delivery, at twice the minimax-h3 rate; the inputs are the same.
minimax-h3-normal5–15480p, 768p, 1080p41—Price matters most and you can wait longer: it renders more slowly about a third below the minimax-h3 rate at 768p, adds a seed, and takes fewer references (no audio).
minimax-h3-max5–15480P, 768P, 1080P———You start from text or one or two frames, want 480P, 768P or 1080P, and want a seed; it takes no reference inputs and no aspect_ratio.
minimax-h3-max-turbo5–15480P, 768P, 1080P———Same inputs and resolutions as minimax-h3-max at half its list price.

Endpoint and authentication

POST https://api.beatapi.io/v1/videos/tasks

Authorization string Required

Your BeatAPI API key, sent as Bearer <BEATAPI_API_KEY>. Create keys in the Dashboard. Keep keys on your server; never ship them in a browser or mobile app.

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

1

Create the task

POST the parameters below to the endpoint. A 201 means the task was accepted and its price reserved from your balance; the work runs in the background. Save data.id.

2

Wait for it to finish

Call GET /v1/tasks/{task_id} and wait data.poll_after_seconds between calls (5 s for images, 8 s for videos) until status is succeeded or failed. Or register a webhook for task.succeeded and task.failed; keep polling as the fallback, because a task stopped by the processing timeout sends no event.

3

Save the result

On succeeded, download every data.output.media[].url and store the files you need; BeatAPI does not promise how long result URLs stay available. On failed, read data.error_code and data.error_message: the reserved amount was returned to your balance, and data.retryable says whether sending the same request again can succeed.

Input modes

ModeRequired inputsNotes
Text to videomodel, promptSend no media arrays.
First framemodel, prompt, images (1 link)The video starts from the image. Send an aspect_ratio that matches the image.
First and last framemodel, prompt, images (2 links)images[0] is the first frame, images[1] the last.
Referencesmodel, prompt, at least one of reference_images, reference_videosUp to 4 images and 1 video. Cannot be combined with images. Reference audio is not supported.

Request parameters

model string Required

The model to run.

Value: minimax-h3-normal

If the value is wrong

  • Missing: "model" is required
  • An image model sent to this endpoint: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

prompt string Required

What happens in the video: subject, action, camera movement, style and sound. With references, say what each input is for.

Length: 1–5000 characters

  • Length is counted in characters (a CJK character counts as one).
  • Refer to inputs by their position, for example “the first reference image”.

If the value is wrong

  • Missing: "prompt" is required
  • Empty or longer than the limit: "prompt" has an unsupported length

images string[] Optional

A first frame, or a first and a last frame.

Items: 1–2
Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • One link: the video starts from this image. Two links: images[0] is the first frame and images[1] the last.
  • For pictures that guide the video without being frames, use reference_images instead.

If the value is wrong

  • More than two links: "images" accepts at most 2 items
  • Combined with any reference_* field: Cannot combine "images" with reference inputs in one task
  • Not an https:// link: "images[0]" must be a public HTTPS URL

reference_images string[] Optional

Pictures that guide the content, characters, products or style of the video.

Items: 1–4
Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • Refer to them in the prompt by position.

If the value is wrong

  • More than the maximum: "reference_images" accepts at most 4 items
  • Combined with images: Cannot combine "images" with reference inputs in one task

reference_videos string[] Optional

One video to take motion, camera work or content from.

Items: 1–1
Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • At most 15 seconds, at 23.976 to 60 frames per second; see the limits below.
  • The length of the reference video does not change the price.

If the value is wrong

  • More than one link: "reference_videos" accepts at most 1 items
  • Longer than the limit: The reference videos run 20 seconds in total; this model takes at most 15.
  • Frame rate outside the limit: reference_videos[0] runs at 12 frames per second; this model takes 23.976 to 60.

duration integer OptionalDefault: 5

Length of the video in seconds, a whole number.

Default: 5
Range: 5–15

  • If you leave it out, 5 is used.
  • The price follows this value (see Billing).

If the value is wrong

  • Outside the range or not a whole number: "duration" is outside its supported range

aspect_ratio string OptionalDefault: 16:9

Shape of the video as width:height.

Allowed values: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9
Default: 16:9

  • If you leave it out, 16:9 is used. This default is also sent when you pass images or references, so set aspect_ratio to match your input (for example 9:16 for a portrait frame).
  • adaptive is not available on this model; send a fixed ratio.

If the value is wrong

  • A value not in the list (for example adaptive): "aspect_ratio" must be one of: [16:9 9:16 1:1 4:3 3:4 21:9]

resolution string OptionalDefault: 768p

Output resolution. Higher resolution costs more per second.

Allowed values: 480p, 768p, 1080p
Default: 768p

  • Upper or lower case, so 768p and 768P mean the same.
  • 2K and 4K are not offered on Normal; for 2K use minimax-h3-fast.

If the value is wrong

  • A value not in the list (for example 2K or 4K): "resolution" must be one of: [480p 480P 768p 768P 1080p 1080P]

seed integer Optional

A fixed number to seed the generation. Leave it out for a random seed.

Range: 0–9007199254740991

  • A whole number from 0 up to 9007199254740991.

If the value is wrong

  • Outside the range or not a whole number: "seed" is outside its supported range

The gateway also checks these combinations before creating the task:

  • images cannot be combined with reference inputs
  • Normal renders more slowly about a third below the minimax-h3 rate at 768p; only 480p, 768p and 1080p are available
  • reference mode accepts up to four images and one video; reference audio is not supported; generated videos include native audio

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

MediaLimits checked before the task is created
Imageswidth and height 256–5760 px; aspect ratio (width ÷ height) 0.4–2.5
Videos15 s in total; 23.976–60 FPS
  • The limits apply to images and reference_images (images) and reference_videos (video). Reference audio is not accepted on this model, so the audio row does not apply.
  • Inputs are checked one by one, in the order images, reference_images, reference_videos. For one input the order is length, sides, aspect ratio, frame rate; the total length of all reference videos is checked last. The message names the input by list and position, counting from 0 like the field errors: images[0] is 200x200 pixels; this model takes images 256 to 5760 pixels on each side.
  • Lengths are measured with a 0.1-second tolerance. Sizes are checked only when the host reports them.
  • A link is refused at create only when its host answers with an HTTP 4xx error or returns an empty file, for example reference_videos[0] could not be downloaded: the URL returned HTTP 404.; other problems with an input surface after submission and fail the task (refunded).
  • Have a local file? Upload it with POST /v1/files and pass the returned data.url.

Sound and fields this model does not accept

Every video has generated sound. There is no generate_audio field and no audio input.

Sending a field the model does not accept is refused before anything is charged, instead of being ignored:

  • reference_audios, generate_audio, watermark, quality, sound and any other field from other video models → field "reference_audios" is not supported by model minimax-h3-normal (with the field you sent).
  • Any other unknown field → unknown field: <name>.

Request examples

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768p"
}'

Text to video

A 5-second 768p landscape clip with sound.

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768p"
}'

First frame

The video starts from the image; aspect_ratio matches its portrait shape.

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "The performer turns toward the camera as neon light sweeps across the stage",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 5,
"aspect_ratio": "9:16",
"resolution": "768p"
}'

First and last frame

The video moves from the first image to the second, at 1080p.

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "The camera moves smoothly from the bottle on the table to the singer on a neon stage in one continuous shot",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 6,
"aspect_ratio": "9:16",
"resolution": "1080p"
}'

Image references with a seed

Two reference images, a fixed seed and the cheapest resolution.

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "The singer from the first reference image walks past the bottle from the second reference image, neon reflections, slow tracking shot",
"reference_images": [
"https://cdn.beatapi.io/samples/neon-singer.png",
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"duration": 5,
"aspect_ratio": "9:16",
"resolution": "480p",
"seed": 42
}'

Image and video references

Replace the video link with your own MP4 or MOV of at most 15 seconds, at 23.976 to 60 frames per second.

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3-normal",
"prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the reference video",
"reference_images": [
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"duration": 8,
"resolution": "768p"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3-normal",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3-normal",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 8,
"output": null,
"usage": {
"credits_reserved": 0.1,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.1,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
FieldTypeDescription
data.idstringTask ID: task_ followed by 32 letters and digits. Use it to poll and to match webhook events.
data.objectstringAlways task.
data.task_kindstringimage or video.
data.capability_idstringThe model ID you sent.
data.capability_versionintegerContract version of the model, currently 1.
data.media_typestringimage or video.
data.modelstringThe model ID you sent (same as capability_id).
data.statusstringqueued, processing, succeeded or failed. Only the last two are final.
data.stagestringRepeats status; kept for older clients.
data.created_atintegerWhen the task was created, Unix seconds.
data.updated_atintegerLast change, Unix seconds.
data.completed_atinteger | nullWhen the task finished, Unix seconds; null while it runs.
data.poll_after_secondsintegerWhile running: how long to wait before the next poll (5 for images, 8 for videos).
data.typical_secondsobjectWhile running, when enough recent tasks exist: p50 and p90 completion times in seconds over the last window, from samples tasks.
data.outputobject | nullThe result; null until status is succeeded. See the output fields below.
data.usage.credits_reservednumberUSD held from your balance when the task was created.
data.usage.credits_chargednumberUSD this task costs; 0 on a failed task.
data.usage.credits_settlednumberUSD finally taken; set when the task succeeds, otherwise 0.
data.usage.credits_refundednumberUSD returned to your balance; equals the reservation on a failed task once the refund is recorded.
data.usage.billable_duration_secondsintegerVideo only: the seconds the price is based on. Absent when the model reports no duration.
data.request_idstringRequest ID. Include it when you contact support.
data.error_codestring | nullFailure code; null unless the task failed.
data.error_messagestring | nullWhat went wrong and what to change; null unless the task failed.

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3-normal",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3-normal",
"status": "succeeded",
"stage": "succeeded",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": {
"media": [
{
"type": "video",
"url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
"mime_type": "video/mp4"
}
],
"r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
},
"usage": {
"credits_reserved": 0.1,
"credits_settled": 0.1,
"credits_refunded": 0,
"credits_charged": 0.1,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}

Output fields

FieldTypeDescription
output.mediaobject[]The generated files; one video for this model.
output.media[].typestringAlways video.
output.media[].urlstringHTTPS link to the stored video. Download and keep it; no retention period is promised.
output.media[].mime_typestringThe file type, for example video/mp4.
output.r2_urlstringThe video URL again, for older clients. Read media instead.

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3-normal",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3-normal",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.1,
"credits_settled": 0,
"credits_refunded": 0.1,
"credits_charged": 0,
"billable_duration_seconds": 5
},
"retryable": true,
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": "processing_failed",
"error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
}
}
FieldTypeDescription
data.error_codestringOne of bad_request and content_policy_violation (change the request) or processing_unavailable, processing_timeout, processing_failed and result_transfer_failed (try again later). See Errors.
data.error_messagestringA sentence that names the problem and the fix.
data.retryablebooleanPresent only on a failed task: true when the same request can succeed if you send it again.
data.usageobjectOnce the refund is recorded (normally at the moment the task fails): credits_charged and credits_settled are 0, and credits_refunded equals credits_reserved.

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
# One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
for attempt in range(3):
response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
if response.status_code in (429, 503) and attempt < 2:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
break
try:
payload = response.json()
except ValueError: # an edge error page is not JSON
response.raise_for_status()
raise
if not response.ok:
error = payload["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
response.raise_for_status()
task = response.json()["data"]
if task["status"] in ("succeeded", "failed"):
return task
time.sleep(task.get("poll_after_seconds", 5))
raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
"model": "minimax-h3-normal",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys, distant bells",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
print(item["url"])

Billing

  • Billed per second of video: the requested duration times the rate of the chosen resolution. The list prices below are for 8 seconds, which works out to about 0.0175persecondat480p,0.0175 per second at 480p, 0.02 at 768p and $0.025 at 1080p.
  • At 768p this is a third below the minimax-h3 rate (768P 0.03persecond;‘minimax−h3−fast‘is0.03 per second; `minimax-h3-fast` is 0.06).
  • The aspect ratio, the number of references, seed and the length of the reference video do not change the price.
  • The price is reserved when the task is created; usage.billable_duration_seconds on the task shows the seconds billed.
  • A failed task, including one refused by moderation after submission, is refunded in full.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

OptionList price (USD)
8 sec · 480p$0.14
8 sec · 768p$0.16
8 sec · 1080p$0.2

Common errors

Error or symptomCauseFix
400 "resolution" must be one of: [480p 480P 768p 768P 1080p 1080P]2K or 4K: Normal has three tiers.Send 480p, 768p or 1080p; for 2K use minimax-h3-fast.
400 "aspect_ratio" must be one of: [16:9 9:16 1:1 4:3 3:4 21:9]adaptive, which this model does not take.Send a fixed ratio, or leave the field out for 16:9.
400 "duration" is outside its supported rangeNot a whole number from 5 to 15, or sent as a string.Send an integer such as 5.
400 field "reference_audios" is not supported by model minimax-h3-normalNormal takes no audio input (also generate_audio: sound is always on).Remove the field, or use minimax-h3-fast for audio references.
400 "reference_videos" accepts at most 1 itemsNormal takes one reference video (and up to 4 reference images).Send one video, or use minimax-h3-fast for up to 3.
400 Cannot combine "images" with reference inputs in one taskFrames and reference_* in the same request.Use frames or references. For several pictures, put them all in reference_images.
400 The reference videos run 20 seconds in total; this model takes at most 15.The reference clip is too long.Trim the clip.
400 "seed" is outside its supported rangeA negative or fractional seed, or one above 9007199254740991.Send a whole number from 0 up to 9007199254740991, or leave seed out.
Task failed with content_policy_violationThe prompt, an input or the result was refused by moderation.Change the prompt or the inputs. Retrying unchanged fails again; nothing is charged.
402 insufficient_creditsThe balance is below the price reserved for the request.Top up, or lower duration or resolution.

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
"error": {
"code": "bad_request",
"message": "\"prompt\" is required",
"retryable": false,
"request_id": "req_5f0c2a9e4b7d4e31"
}
}
HTTP statuserror.codeWhat to do
400bad_request, content_policy_violationFix the request; the message names the field. Do not retry unchanged.
401missing_api_key, invalid_api_key (older clients may see unauthorized)Send a valid key as Authorization: Bearer <key>.
402insufficient_creditsTop up, or raise the key’s quota, then send it again.
403forbiddenThe key or account may not use this model (for example, free credit only covers some models). Do not retry unchanged.
404not_foundOn GET /v1/tasks/{task_id}: the task does not exist for this key’s account. Check the ID.
409idempotency_conflictUse a new Idempotency-Key, or wait for the first request with this key to finish.
429rate_limit_exceededWait Retry-After seconds (also error.retry_after_seconds), then retry.
500internal_errorRetry with backoff; contact support with request_id if it continues.
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failedNothing was charged. Retry with exponential backoff.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

Idempotency-KeystringOptional<=255 characters

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

Request

This endpoint expects an object.
modelenumRequired

The model to run.

Value: minimax-h3-normal

If the value is wrong

  • Missing: "model" is required
  • An image model sent to this endpoint: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
Allowed values:
promptstringRequired1-5000 characters

What happens in the video: subject, action, camera movement, style and sound. With references, say what each input is for.

Length: 1–5000 characters

  • Length is counted in characters (a CJK character counts as one).
  • Refer to inputs by their position, for example “the first reference image”.

If the value is wrong

  • Missing: "prompt" is required
  • Empty or longer than the limit: "prompt" has an unsupported length
aspect_ratioenumOptionalDefaults to 16:9

Shape of the video as width:height.

Allowed values: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9

Default: 16:9

  • If you leave it out, 16:9 is used. This default is also sent when you pass images or references, so set aspect_ratio to match your input (for example 9:16 for a portrait frame).
  • adaptive is not available on this model; send a fixed ratio.

If the value is wrong

  • A value not in the list (for example adaptive): "aspect_ratio" must be one of: [16:9 9:16 1:1 4:3 3:4 21:9]
durationintegerOptional5-15Defaults to 5

Length of the video in seconds, a whole number.

Default: 5

Range: 5–15

  • If you leave it out, 5 is used.
  • The price follows this value (see Billing).

If the value is wrong

  • Outside the range or not a whole number: "duration" is outside its supported range
imageslist of stringsOptional

A first frame, or a first and a last frame.

Items: 1–2

Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • One link: the video starts from this image. Two links: images[0] is the first frame and images[1] the last.
  • For pictures that guide the video without being frames, use reference_images instead.

If the value is wrong

  • More than two links: "images" accepts at most 2 items
  • Combined with any reference_* field: Cannot combine "images" with reference inputs in one task
  • Not an https:// link: "images[0]" must be a public HTTPS URL
reference_imageslist of stringsOptional

Pictures that guide the content, characters, products or style of the video.

Items: 1–4

Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • Refer to them in the prompt by position.

If the value is wrong

  • More than the maximum: "reference_images" accepts at most 4 items
  • Combined with images: Cannot combine "images" with reference inputs in one task
reference_videoslist of stringsOptional

One video to take motion, camera work or content from.

Items: 1–1

Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.

  • At most 15 seconds, at 23.976 to 60 frames per second; see the limits below.
  • The length of the reference video does not change the price.

If the value is wrong

  • More than one link: "reference_videos" accepts at most 1 items
  • Longer than the limit: The reference videos run 20 seconds in total; this model takes at most 15.
  • Frame rate outside the limit: reference_videos[0] runs at 12 frames per second; this model takes 23.976 to 60.
resolutionenumOptionalDefaults to 768p

Output resolution. Higher resolution costs more per second.

Allowed values: 480p, 768p, 1080p

Default: 768p

  • Upper or lower case, so 768p and 768P mean the same.
  • 2K and 4K are not offered on Normal; for 2K use minimax-h3-fast.

If the value is wrong

  • A value not in the list (for example 2K or 4K): "resolution" must be one of: [480p 480P 768p 768P 1080p 1080P]
Allowed values:
seedintegerOptional0-9007199254740991

A fixed number to seed the generation. Leave it out for a random seed.

Range: 0–9007199254740991

  • A whole number from 0 up to 9007199254740991.

If the value is wrong

  • Outside the range or not a whole number: "seed" is outside its supported range

Response

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error