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-h3rate 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.
seedis optional. - Billed per second of video. A failed task costs nothing.
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.
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
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.
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.
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
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 andimages[1]the last. - For pictures that guide the video without being frames, use
reference_imagesinstead.
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,
5is 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:9is used. This default is also sent when you passimagesor references, so setaspect_ratioto match your input (for example9:16for a portrait frame). adaptiveis 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
768pand768Pmean 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
2Kor4K):"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.
- The limits apply to
imagesandreference_images(images) andreference_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/filesand pass the returneddata.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,soundand 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
Text to video
A 5-second 768p landscape clip with sound.
First frame
The video starts from the image; aspect_ratio matches its portrait shape.
First and last frame
The video moves from the first image to the second, at 1080p.
Image references with a seed
Two reference images, a fixed seed and the cheapest resolution.
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.
Responses
Create a task (201)
The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.
Finished task
GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.
Output fields
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.
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.
Billing
- Billed per second of video: the requested
durationtimes the rate of the chosen resolution. The list prices below are for 8 seconds, which works out to about 0.02 at 768p and $0.025 at 1080p. - At 768p this is a third below the
minimax-h3rate (768P 0.06). - The aspect ratio, the number of references,
seedand the length of the reference video do not change the price. - The price is reserved when the task is created;
usage.billable_duration_secondson 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.
Common errors
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.
Authentication
Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.
Headers
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
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
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
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:9is used. This default is also sent when you passimagesor references, so setaspect_ratioto match your input (for example9:16for a portrait frame). adaptiveis 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]
Length of the video in seconds, a whole number.
Default: 5
Range: 5–15
- If you leave it out,
5is 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
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 andimages[1]the last. - For pictures that guide the video without being frames, use
reference_imagesinstead.
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
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
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.
Output resolution. Higher resolution costs more per second.
Allowed values: 480p, 768p, 1080p
Default: 768p
- Upper or lower case, so
768pand768Pmean 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
2Kor4K):"resolution" must be one of: [480p 480P 768p 768P 1080p 1080P]
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.

