MiniMax H3 Reference Video API Guide: Assets, Tasks and Output Review

A MiniMax H3 reference video API workflow needs more than a prompt. You have to label the source assets, submit a task, preserve its identifier and review the resulting clip against those references. A request that completes successfully can still produce a scene unsuitable for publication.

This guide covers the documented H3 V2 API checked on October 14, 2026. It does not claim access to an announced future model, and no paid video request was submitted for this article.

Verify the model and generation mode

The current create-task documentation lists MiniMax-H3 and MiniMax-H3-Max at POST /v2/video_generation. It distinguishes first/last-frame image-to-video from reference-to-video and requires a non-empty text item. Reference roles and first/last-frame roles cannot be mixed in one request. Create-task documentation.

The model choice affects output options. The checked schema gives H3 768P and 2K options, while H3 Max supports 480P and 768P and explicitly excludes 2K. Verify duration and resolution together for the selected model before building your form.

Use a configuration field for the exact model ID. Do not rename it to match an informal social post or infer that a future “fast” release is available. A provider's current API schema is the useful contract for your application.

For broader creative background, see the existing MiniMax H3 prompt tips. This article focuses on assets, asynchronous task handling and output review rather than repeating that prompt guide.

Prepare an asset manifest with explicit roles

Create a manifest before the request. For each file, record its source, permission, technical properties and intended role. Separate a subject reference from a motion reference and a soundtrack reference, even when the same scene contains all three.

Keep the first prototype small: one permitted image and a brief prompt with a clear action. Then add a video or audio reference separately. If several inputs contradict each other, you need a review rule for which instruction should take priority; otherwise an unexpected result is difficult to diagnose.

The schema documents limits of nine reference images, three reference videos and three reference audio clips, with further file and duration constraints. Those are input ceilings, not a recommendation to fill every slot. Validate each asset against the current table before submission.

If you provide URLs, make sure the service can retrieve the intended file during processing. Avoid relying on a link that immediately expires or redirects to an authenticated page. Use an authorized asset delivery method and retain the association between that URL and your original source file.

Submit once and retain the task record

Build the request's content array with the documented media types and roles. Include the prompt, model, resolution and duration. Validate the payload locally before sending it; a form that permits incompatible roles creates avoidable task failures.

Store a request identifier in your application alongside the returned task_id. Also save the asset manifest and the selected options without saving API secrets. This lets a support operator identify which inputs produced a particular clip.

Treat an interrupted create request carefully. If the server accepted the task before the connection failed, immediately submitting another request can produce duplicate work. Inspect the available task-management paths and your own request record before retrying. Do not assume an idempotency feature unless the API documents one.

Keep generation permission separate from preview preparation. An application can let an editor assemble assets and validate a request before the action that incurs generation cost. That separation also makes a specific batch reviewable.

Poll status and preserve the successful output

The V2 query path is GET /v2/query/video_generation/{task_id}. The documented response places the generated video URL under the successful task's content. The query window is limited to recent tasks, and output URLs are time-limited. Query-task documentation.

Poll at a bounded interval and stop on a terminal result. Save the provider's status and error details rather than replacing every failure with a generic “try again.” Use backoff for transient failures so many browser clients do not continuously hammer the endpoint.

After success, copy or store the output promptly in the authorized destination for your workflow. Keep the generated asset's identifier separate from the temporary provider URL. A task marked successful is not a durable asset library if the only saved pointer later expires.

Record returned usage when available. Do not estimate a final bill from output duration alone if the selected route has other billable inputs. The provider's current pricing and the actual usage record belong together in cost review.

Review the clip against the source manifest

Watch the whole clip before inspecting selected frames. Check subject continuity, the intended action, scene transitions and any audio relationship. A good opening frame does not establish that a product remains consistent throughout the motion.

Use the manifest to make the review concrete:

Keep rejected outputs with a short reason and the task record. That gives you an evidence set for prompt revision and provider changes. Final publication also needs the normal editorial and source-permission review for the resulting asset.

Worked task: producing a short product-motion preview

Imagine a design team evaluating a five-second motion preview for an unbranded sample object. Use a permitted photograph as the subject reference and write a brief describing one action, such as a slow rotation on a plain tabletop. Avoid combining several scene changes in the first request.

Create an asset manifest with the photograph's identifier, source permission and technical properties. Keep a copy of the approved brief. Validate the selected model, duration, resolution and role combination against the current API schema before the generation action is authorized.

After submission, save the task identifier and request record. When the task succeeds, preserve the output in the team's authorized asset store and link it back to the manifest. The provider URL is a retrieval location, not the permanent identity of your production asset.

Review the preview from beginning to end. Check whether the object's shape, number of components and surface markings remain consistent during rotation. A correct first frame followed by a distorted side view fails a subject-continuity requirement even if the motion itself is smooth.

Only then add a motion reference video. Define which aspect it should supply: camera motion, subject movement or timing. Compare the result with the image-only request and note both improvements and unwanted changes. This isolates the contribution of the new reference instead of attributing every difference to a revised prompt.

If an audio reference is added later, give it a clear role and review its relationship with the generated scene. Do not assume that successful submission means the sound is synchronized or appropriate. Keep creative approval separate from the task's technical completion status.

Design the application task record before the API call

Use a local task record with fields for the approved brief, asset manifest, exact model, selected options and provider task ID. Include timestamps for submission, status updates, output retrieval and editorial approval. Those events answer different questions and should not collapse into one “done” value.

Keep the local request identifier available even before the provider returns a task ID. If the connection fails during creation, that record can show whether the editor initiated a request and what was sent. Preserve enough context to investigate duplicate work without logging the API key or private access credentials.

Separate provider state from application state. A provider task may be successful while your output download fails. Your application can then report “generation succeeded, retrieval pending” rather than misleading the editor into regenerating a clip that already exists.

Add a distinct editorial status after retrieval. Suggested states include awaiting review, approved and rejected, but choose names that fit your existing asset workflow. The key property is that a successful API task cannot silently become an approved public asset.

Keep rejection reasons attached to the output and its inputs. A note such as “side panel changes shape after the second second” is actionable. A generic “bad result” makes later prompt and reference experiments harder to interpret.

Validate media beyond filename extensions

Inspect the actual file properties of each reference. A file named .mp4 can still contain a codec or stream combination outside the documented requirements. Record dimensions, duration and codecs in the manifest, and validate them before submission.

Check the aggregate limits as well as per-file limits. Several individually valid references can exceed a combined duration or request-size boundary. Use the current schema's tables to build validation and retain a dated version of those rules with the integration.

Test asset retrieval from the provider's perspective where your authorized delivery method permits it. A URL that works in an authenticated editor's browser may return a login page or expire before asynchronous processing reads it. Use a permitted delivery path and a lifetime appropriate to the task.

Avoid embedding unnecessary metadata or unrelated files in the asset package. The generation task should receive the approved references for that brief. Keeping the package small makes technical failures easier to diagnose and permission review more concrete.

When you transform a reference to meet technical constraints, preserve the original and document the working copy. Cropping, resizing or trimming can remove the visual or audio cue the editor intended to supply. Review the transformed asset before approving the request.

Handle polling, cancellation and uncertain creation separately

Polling should read the existing task rather than create new work. Associate each poll with the provider task ID and stop at a documented terminal state. Keep a bounded retry policy for temporary query failures and a visible state when status cannot currently be retrieved.

For an uncertain create response, inspect the task list or other documented management surfaces available to your account before submitting another paid request. Match using your saved time, model and input context where possible. Do not fabricate an idempotency guarantee for an endpoint that has not documented one.

If the application supports cancellation, use the provider's current documented task-management behavior and distinguish it from deleting a local row. Removing a task from the editor's queue does not necessarily stop upstream generation or its cost.

Test what happens when the editor closes the browser after submission. A server-side task record should allow the user to return and find the ongoing work. A poller that exists only in the page can lose visibility even though the provider keeps processing.

When retrieval fails after success, retry retrieval within the URL's valid lifetime rather than generating again. Save the failure reason and surface it to an operator when necessary. This separates infrastructure repair from another creative generation attempt.

Build an output review rubric from the brief

Convert each requirement into an observable question. Subject continuity asks whether identifying details persist. Motion asks whether the intended action occurs coherently. Composition asks whether the subject remains framed as requested. Audio review asks whether the sound supports the scene without unexpected content.

Watch the entire clip at normal speed, then inspect difficult moments frame by frame. Normal playback catches timing and coherence problems; selected frames catch changes in geometry or markings. Neither review alone covers the complete requirement.

Record the output's actual technical properties after download. Confirm duration, resolution, audio presence and decodability in your publishing environment. An API option describes what was requested; the saved file is the evidence of what your workflow received.

For a commercial product, compare the generated object with the reference evidence. An attractive accessory or altered feature should not be treated as part of the real product. If the output is a concept visualization, label it accordingly rather than using it as a factual product demonstration.

Keep cost review tied to the actual task record and current pricing. Include retries and rejected takes when assessing the cost of an approved clip. A per-generation rate does not describe the production cost of a final asset if several attempts and reviews are needed.

The final integration decision should state which model and modes were tested, which asset envelope passed and which failures still need review. That gives the team a repeatable creative tool while keeping technical success, asset preservation and publication approval as distinct outcomes.

Conclusion

Build the H3 integration around a versioned request, labeled assets and a durable task record. Preserve successful outputs before their URLs expire, then approve the whole clip against the manifest. That workflow makes a creative revision traceable even when the generation itself is probabilistic.

FAQ

Can first-frame and reference roles share one request?

The checked V2 schema treats those generation modes as mutually exclusive. Validate the role combination before submission.

Does H3 Max currently support 2K output?

The checked documentation explicitly excludes 2K for H3 Max. Confirm the current schema for the exact model before configuring output options.

Is a succeeded task ready to publish?

It confirms generation completion. Preserve the output and review continuity, instructions, audio and source permissions before publication.