MiniMax H3 supports three video workflows under the same minimax-h3 model ID: prompt-only generation, first and last frame control, and multimodal reference video. A reliable integration starts by choosing one workflow, proving the asynchronous task lifecycle with the smallest valid input, and separating request validation from generation failures.
Use the MiniMax H3 API parameter and request schema when you need field names, limits, callbacks, or copyable curl, Python, and Node.js examples. This guide focuses on the decisions and debugging sequence around those requests.
Choose the workflow before building the payload
Text-to-video is the quickest way to prove access and task handling. Send a prompt and let the documented defaults handle duration, resolution, aspect ratio, and watermark while you confirm that the account, model ID, and result pipeline work.
Frame control fits a shot that must begin from a supplied image or resolve into a specified final image. A last frame depends on a first frame, so validate the pair together before submission.
Multimodal reference mode fits work where subject identity, camera language, motion, or rhythm comes from existing images, video, or audio. Reference media and frame-control fields select different modes and should not be combined in one request. The complete media counts, durations, and field combinations stay in the API reference so this tutorial does not create a second schema source.
| Production goal | Start with | What to validate first |
|---|---|---|
| Prove the integration | Text-to-video | API key, minimax-h3, task creation, result download |
| Control the opening or ending | First or first/last frame | Public image access and the frame pair |
| Preserve a subject or visual language | Multimodal references | Public media access and a single reference-mode payload |
Prove one complete task before adding controls
Copy the minimal request from the MiniMax H3 API reference. A successful create response returns data.taskId immediately. HTTP 200 confirms that HiAPI created the task; it does not mean video generation has finished.
For local debugging, wait briefly and query GET /v1/tasks/{taskId}. Follow the task through its non-terminal states and stop only at success or fail. On success, read the generated video from data.output[].url. Check expireAt and download the asset before the temporary URL expires, or choose persistent storage when the asset must remain available.
This smallest end-to-end run gives you a known-good baseline. Add duration, framing, or references one change at a time. When a later request fails, the difference from that baseline is small enough to inspect.
Debug request errors separately from task failures
A synchronous HTTP error means no usable task lifecycle started. Inspect the response before changing polling code. A 400 INVALID_REQUEST points to the request body, such as an invalid duration or a field combination that selects two modes. A 401 or 402 points to credentials, access, or balance. A 415 points to the request content type. A 503 is temporary platform availability and should be retried later with backoff.
A task can also be created successfully and later reach status: "fail". In that case, keep the original taskId and read data.error.code and data.error.message. Check whether every input asset is reachable over public HTTPS and whether the selected fields belong to one mode. Resubmitting the same payload without understanding the failure can create duplicate work and duplicate billing.
| Symptom | Debug layer | Next action |
|---|---|---|
HTTP 400 before taskId | Request validation | Fix the named field or incompatible mode combination |
| HTTP 401, 402, or 415 | Account or transport | Check the key, balance, and JSON content type |
HTTP 503 before taskId | Temporary availability | Retry later with exponential backoff |
status: "fail" after taskId | Generation task | Inspect data.error and public input assets |
success with a temporary URL | Output handling | Download before expireAt or use persistent storage |
Move from polling to a production-safe flow
Polling is useful while debugging because you can watch every state transition. Production services should send a top-level callback.url and use callback.when: "final" for terminal notifications. The callback can report either success or failure, so handle both and deduplicate processing by taskId.
Use an Idempotency-Key when a create request may be retried. Reusing the same key with the same request returns the original taskId, which protects the create boundary from accidental duplicates. Keep slow polling as reconciliation if a callback is delayed or missed, and stop polling as soon as the task reaches a terminal state.
Output handling belongs in the same production checklist. Temporary output URLs have an access deadline. Download promptly, request persistent storage at creation, or promote the asset before expiry based on your retention needs.
Use the model page for evaluation and the reference for implementation
The MiniMax H3 video generator page is the right place to compare capabilities, view current usage pricing, and test the model in Playground. It intentionally avoids duplicating the request schema.
The MiniMax H3 API reference remains the source for parameters, constraints, callbacks, and copyable code. The Unified Async API lifecycle covers shared task headers, status values, callback behavior, and storage across models.
FAQ
Which MiniMax H3 mode should I test first?
Start with prompt-only text-to-video. It has the fewest moving parts and proves the API key, model ID, asynchronous task lifecycle, and output download before you add media inputs.
Why did the create request return 200 without a video?
Video generation is asynchronous. The create response returns data.taskId; retrieve the task later or wait for a callback, then read data.output[].url only after status reaches success.
Should I retry a failed request?
Fix synchronous validation errors before resubmitting. Retry a create-time 503 with backoff. Once a taskId exists, inspect that task or wait for its callback instead of submitting an identical request again.
Where should I check the current MiniMax H3 price?
Use the MiniMax H3 model page. It reads the current HiAPI pricing configuration, while this tutorial avoids a price value that can become stale.
