# MiniMax H3 video API > Text and image video generation, first/last frames, video and audio references, file uploads, 2K regeneration, prompt optimization and reservation-based billing with complete API examples. Web page: https://wanapi.ai/docs/minimax-h3 Last verified: 2026-11-04 · Protocol candidate; no real paid generation Use model minimax-h3. Submit an asynchronous task, save its public ID, then query and download it. Current capability and pricing responses determine which advanced inputs and operations are enabled. Replace example IDs, files and environment values before use. Generation, regeneration and prompt optimization incur charges. ## At a glance | Item | Value | | --- | --- | | Authentication | Authorization: Bearer $WANAPIS_API_KEY; the key must allow minimax-h3 and the relevant group under the same account | | Defaults | 4 seconds, 768P, 9:16, fast_mode=false, context_ir_enabled=true | | Output | 480p / 768P / 1080p / 2K; 4–30 seconds, up to 15 seconds at 2K; no 4K tier | | Reference counts | Up to 9 images, 3 reference videos and 3 reference audio clips; combinations are validated per operation | | Reference duration | Keep reference video total at 15 seconds or less; the single-clip 15.5-second tolerance follows current capabilities. Audio totals at most 15 seconds | | Upload limits | Platform limits: 30 MiB/image, 31 MiB/video, 15 MiB/audio; 32 MiB total request body including multipart/JSON overhead. The published effective limits take precedence | | Currency | 500000 quota = CNY 1. All prices below are in CNY; apply the effective group multiplier to the total | | Live capabilities and prices | GET /api/pricing → minimax-h3 video_pricing and video_pricing_meta.advanced. Missing advanced metadata means legacy capabilities only | ## Setup steps ### 1. Check capabilities and prices Normal output and reference-video base rates per second are CNY 0.078 at 480p, 0.117 at 768P, 0.182 at 1080p and 0.195 at 2K. The first five images are free; additional normal images cost CNY 0.065 each. Reference audio is free. Built-in IR is CNY 0.065 per request by default. Examples assume group multiplier 1. Live marketplace/API prices, available operations and effective limits take precedence; never guess a missing fee. **pricing** ``` curl https://api.wanapis.com/api/pricing ``` ### 2. Submit a minimal text task Prefer POST /v1/videos. POST /v1/video/generations and /v1/videos/generations remain compatible. Save the returned id; acceptance is not completion. Use seconds or duration; if both are supplied they must agree. Resolution, ratio and legacy size selectors must also agree. A 4.0 literal, fractions, string booleans and unknown fields are rejected. **text-to-video** ``` curl https://api.wanapis.com/v1/videos \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "prompt": "A paper boat crosses a calm lake, slow cinematic tracking shot", "resolution": "768P", "ratio": "16:9", "seconds": 4, "fast_mode": false, "context_ir_enabled": true }' ``` ### 3. Poll using the correct response format GET /v1/videos/{id} returns the OpenAI-style object: top-level status is queued/in_progress/completed/failed, with the completed URL in metadata.url. GET /v1/video/generations/{id} returns the generic envelope: data.status is NOT_START/SUBMITTED/QUEUED/IN_PROGRESS/SUCCESS/FAILURE, with data.result_url. Do not mix their parsers. Poll every 5–10 seconds. A completed video and billing.status=settled are separate states. **poll** ``` curl https://api.wanapis.com/v1/videos/task_example \ -H "Authorization: Bearer $WANAPIS_API_KEY" curl https://api.wanapis.com/v1/video/generations/task_example \ -H "Authorization: Bearer $WANAPIS_API_KEY" ``` ### 4. Download with authentication After success, download with your public task ID and Bearer authentication. The browser workspace uses its same-origin session and supports byte ranges; do not put API keys in media URLs. There is no universal 24-hour retention guarantee. Save results promptly and do not invent expires_at when it is absent. Closing the page or stopping polling does not cancel an accepted task. **download** ``` curl https://api.wanapis.com/v1/videos/task_example/content \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ --output result.mp4 ``` ### 5. Upload local files first Upload one file per request with media_type=image, video or audio. Put the model, media_type and optional binding_asset_id text fields before the final file part. The response is a platform asset handle in id, not a generation task. Use the first returned id as binding_asset_id for subsequent files in the same group. Assets must belong to you and remain valid. Replace asset_image_example with the actual returned ID. Small public URL inputs may instead use url directly in content. Browser-reported duration is not used for billing. **upload** ``` curl https://api.wanapis.com/v1/videos/assets \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -F 'model=minimax-h3' \ -F 'media_type=image' \ -F 'file=@./reference.webp' curl https://api.wanapis.com/v1/videos/assets \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -F 'model=minimax-h3' \ -F 'media_type=video' \ -F 'binding_asset_id=asset_image_example' \ -F 'file=@./motion.mp4' ``` ### 6. Combine image, video and audio references Include one text item plus typed references in content. Each media source has exactly one of url or asset_id. Do not combine content with legacy prompt/input_reference/images inputs. Image counts include every role; the first five are free. Reference videos are billed by their combined input duration rounded up to whole seconds. Free audio does not make the generated video free. Replace all three sample asset IDs. **multimodal** ``` curl https://api.wanapis.com/v1/videos \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "resolution": "768P", "ratio": "16:9", "seconds": 4, "fast_mode": false, "context_ir_enabled": false, "content": [ { "type": "text", "text": "A paper boat crosses a calm lake, slow cinematic tracking shot" }, { "type": "image_url", "role": "reference_image", "image_url": { "asset_id": "asset_image_example" } }, { "type": "video_url", "role": "reference_video", "video_url": { "asset_id": "asset_video_example" } }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "asset_id": "asset_audio_example" } } ] }' ``` ### 7. Use explicit first and last frames Use first_frame and last_frame for frame conditioning, at most one each. One asset cannot occupy both roles. Legacy input_reference accepts a URL string or an image_url object and is treated as reference_image, not an explicit first frame. Adding reference video may require converting frame roles to references; follow the operation's combination validation rather than assuming all models share the same rules. **first-last-frames** ``` curl https://api.wanapis.com/v1/videos \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "resolution": "768P", "ratio": "16:9", "seconds": 4, "context_ir_enabled": false, "content": [ { "type": "text", "text": "A paper boat crosses a calm lake, slow cinematic tracking shot" }, { "type": "image_url", "role": "first_frame", "image_url": { "asset_id": "asset_first_example" } }, { "type": "image_url", "role": "last_frame", "image_url": { "asset_id": "asset_last_example" } } ] }' ``` ### 8. Optimize and save the final prompt The separate prompt-optimization endpoint creates a charged text task. Save its id and GET /v1/videos/prompt-optimizations/{id}; successful text is in result.text. Current capabilities determine availability. When using that text for a video, explicitly set context_ir_enabled=false to avoid another built-in optimization. Save the final prompt and all original references for later regeneration. **prompt-optimization** ``` curl https://api.wanapis.com/v1/videos/prompt-optimizations \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "seconds": 4, "ratio": "16:9", "content": [ { "type": "text", "text": "A paper boat crosses a calm lake, slow cinematic tracking shot" } ] }' curl https://api.wanapis.com/v1/videos/prompt-optimizations/task_example \ -H "Authorization: Bearer $WANAPIS_API_KEY" ``` ### 9. Regenerate your own original 768P video at 2K The source must be your successful minimax-h3 original at 768P and 4–15 seconds. Output is fixed to 2K; this is not arbitrary-video upscaling. Replace task_source_example with the platform source ID. Use mode=source only when the source's available modes include source; never automatically retry between modes. mode=content requires the unchanged final prompt and every original image/video/audio reference. The service adds your source video itself; do not supply base_video or an internal task ID. If built-in IR changed the original prompt and its final text is unavailable, the initial prompt is not a valid replacement. Historical tasks expose less verifiable evidence; follow their eligibility result. The source must remain unmodified and satisfy audio-track, 24 FPS, dimensions divisible by 32, 768P-area and frame-count requirements. Matching a URL cannot prove its bytes are unchanged. The provider may round the finished duration up for billing, so a regeneration can remain pending_usage until verified; the reservation is not the final charge. **regeneration** ``` curl https://api.wanapis.com/v1/videos/task_source_example/regenerations \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "mode": "source", "resolution": "2K" }' curl https://api.wanapis.com/v1/videos/task_source_example/regenerations \ -H "Authorization: Bearer $WANAPIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-h3", "mode": "content", "resolution": "2K", "content": [ { "type": "text", "text": "Replace with the original final prompt, unchanged" }, { "type": "image_url", "role": "reference_image", "image_url": { "asset_id": "asset_original_example" } } ] }' ``` ### 10. Understand reservations and settlement Normal charge = [output rate × output seconds + reference-video rate × ceil(combined input-video seconds) + extra-image rate × max(image count−5,0)] × duration multiplier × priority multiplier + fixed IR fee; multiply the entire total by the effective group ratio. At 16–30 seconds, duration multiplier 2 applies to the whole output and billable references. fast=true adds another ×2. Neither multiplier affects IR. Combine durations before rounding: 1.2 + 1.2 seconds is billed as 3, not 4. Before submission, the service reserves the maximum input allowance (up to 16 billable seconds for one clip or 15 for multiple clips, as shown by the quote), then refunds the difference using verified usage and frozen rates. With billing.status=pending_usage, charged_quota remains unknown; a reservation is not a final charge. Accepted failed tasks receive a full credit refund. A failure refund and a successful-task adjustment are distinct events. Later price changes do not reprice accepted tasks. ### 11. Regeneration and standalone IR are separate charges Regeneration creates a new task while the original generation charge remains. It costs CNY 0.078/output second plus CNY 0.078/original reference-video billable second plus CNY 0.052/image beyond five, then the group multiplier. The original reference inputs are billed again; the source clip itself is not added as another reference-video fee. Regeneration does not automatically inherit long-duration, fast or IR surcharges. Standalone IR costs CNY 0.065 per operation and does not offset another built-in IR call. At multiplier 1, a 4-second 768P clip without paid references costs CNY 0.533 with built-in IR or 0.468 without it; regenerating a 4-second original without paid references costs CNY 0.312. ### 12. Handle errors without duplicate submissions 400 usually means invalid fields, counts, conflicts or unsupported specifications; check authentication, model permission and ownership for 401/403. Reduce the file/body after 413. Insufficient credit prevents a billable task from being created. When a POST times out, disconnects or reports possible acceptance, query any known task ID and keep the request ID for support. Do not blindly resubmit. GET queries may use limited backoff retries. Decide whether to create a new task only after confirming the original failed and its refund was handled. Cancellation is not guaranteed. ## Known limitations - This is a candidate reference for the extended protocol; real paid generation was not performed. Current capabilities, source eligibility and effective account prices determine availability. - Standalone prompt-optimization responses and regeneration modes still require confirmation on the actual running version. Acceptance or an offline example does not prove a finished video or its actual charge. - No 4K, batch n>1, arbitrary-video upscaling or undeclared fields. Resolution tiers do not guarantee exact pixel dimensions. - URLs can expire or change. Save the original final prompt and materials. The platform matches available recorded conditions and does not claim to verify the historical bytes behind mutable URLs. ## FAQ ### Why is a completed video still awaiting settlement? Result delivery and billing are independent. Missing or invalid reference-video metering leaves billing pending_usage. The reserved maximum is not labeled as the verified charge, and missing usage is not treated as zero. Keep the task ID, continue polling or contact support. ### How much will be reserved? The workspace separates determined fees from the maximum reservation using current prices and the server's input bound. A video-reference reservation can exceed the final charge; verified completion refunds the difference. Do not guess missing fees. ### Will my existing single-image request still work? Yes. prompt plus a URL string or image_url object in input_reference remains supported. Legacy size values are 1280x720, 720x1280, 1792x1024 and 1024x1792. Do not mix them with content or contradict other selectors. ### Do free audio and five free images make generation free? No. They waive only those input line items. Output video, reference video, IR and regeneration have their own charges. ### Why can I not query another account's task ID? Tasks, results and uploaded assets are authenticated by account ownership. Knowing an ID does not grant access. An API key or an authenticated result link is not a public sharing mechanism. --- Generated by the WanAPIs website and kept in sync with the web page. All guides in Markdown: https://wanapi.ai/docs/index.md