Common Errors and FAQ

Common Errors

Error Code / Message	Cause	Handling
`401 unauthorized`	Invalid api_key	Check the authorization header
`400 invalid model`	Wrong model name	Use `minimax_h3`
`400 invalid duration`	Duration outside 5–15 seconds	Adjust `duration`
`400 invalid size`	Malformed size	Use `widthxheight` format, e.g. `1280x720`
`400 invalid image`	Image unreachable or unsupported format	Check that the image URL is publicly reachable
`400 reference limit exceeded`	Reference assets over the limit	At most 1 of each asset type
`429 rate limited`	Too many requests	Lower the polling frequency
`500 upstream error`	Upstream error	Retry later

Be specific in prompts — describe the subject, action, camera, lighting, and style; avoid vagueness.
Set a reasonable duration — longer durations cost more; test with a short duration first.
Prefer public URLs — image / video / audio references must be reachable by the server.
Control the polling frequency — a 5-second interval is recommended, with backoff retries.
Save the task_id — it can be used to resume queries after an interruption.

Which video durations are supported?

5–15 seconds, specified via duration. Values outside this range return a parameter error.

Can I omit the framing parameters?

Yes. When neither size nor aspect_ratio is provided, the server decides using adaptive mode.

Must the first and last frame images share the same ratio?

They should. A large ratio difference causes stretching or cropping.

What if a task times out?

If it does not complete within 10 minutes, treat it as a timeout and resubmit or contact support.

Are failed tasks billed?

No. Failed or cancelled tasks are not billed, and any pre-deducted amount is settled and refunded.

Can the generated result be used commercially?

Refer to the platform's terms of service. You are responsible for ensuring compliance regarding likenesses and copyrighted assets.

How do I get a direct link to the video file?

Call GET /v1/videos/{task_id}/content, which returns the video content or a redirect URL.

Keep the api_key server-side only; never write it into frontend code or public repositories.
Validate the type and size of user-uploaded assets to avoid injection risks.
Record task_id and usage for reconciliation and troubleshooting.
Apply timeout and backoff protection to polling to avoid exhausting upstream quota.