MiniMax H3 API: Which Video Generation Mode Should You Use?

A product photo can play two different parts in an AI video: it can define the opening frame, or it can be a reference for a newly composed shot. That choice matters before you write a long motion prompt. The MiniMax H3 API represents these jobs with different media roles, and the two sets of roles cannot be mixed in one request.

Choose text-to-video when you want to describe a new scene, image-to-video when a starting or ending frame matters, and reference-to-video when images, clips or audio should guide the shot. Through Tokenhot, all three use POST https://api.tokenhot.ai/v1/video/generations with model MiniMax-H3.

This guide explains that input decision using documentation checked on October 26, 2026. The JSON examples were validated offline; no H3 video, output-quality comparison or account charge was produced. It covers choosing and submitting an input, rather than promising a complete task-query and download integration.

Choose what your source material should do

What you need	Scenario	What to provide	Aspect ratio
A new scene described in words	Text-to-video, or t2va	One non-empty text item	A concrete ratio such as 16:9; not adaptive
Motion from a specified opening image, toward an ending image, or between both	Image-to-video, or i2va	Text and first_frame, last_frame, or both	Determined by the image; treated as adaptive
A shot guided by visual or audio references	Reference-to-video, or r2va	Text with reference_image, reference_video, or reference_audio	Defaults to adaptive; a concrete ratio is also allowed

The scenario labels describe the input combinations in the H3 reference. The examples below do not add a separate mode field: the distinction is expressed by the content items and their roles.

For a lamp on a desk, use an opening frame if that composition is the starting point you want to animate. Use reference material if you want to ask for a different shot guided by the assets. Those are prompt-design choices; neither is proof that the generated lamp, label or background will remain unchanged.

Start with text when you are exploring a scene

Text-to-video is the simplest input when you have a scene description but no image to anchor. For example:

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A white ceramic lamp on a wooden desk in soft afternoon light. The camera slowly moves closer in one continuous shot."
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "16:9"
}

Use one non-empty text item. For this text-only scenario, choose the ratio explicitly. Although the field's general default is adaptive, the scenario-specific rule does not allow it for text-to-video.

The documented output settings are 768P or 2K, and an integer duration from 4 to 15 seconds. These are requested settings, not measured delivery time or quality levels. The route documented here is MiniMax-H3; a catalog entry or comparison about H3 Max does not establish a model ID or interchangeable request for this route.

Use frames when the composition is already decided

If your lamp photo should be the opening image, assign it the first_frame role:

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "Starting from this frame, slowly move the camera closer to the lamp while the desk remains still."},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/your-lamp-opening.jpg"},
      "role": "first_frame"
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "adaptive"
}

Replace the example address with an image you may use that the service can retrieve. The role sits alongside type and image_url; it is not a property inside the URL object.

To specify an ending instead, use last_frame. To provide both positions, add a second image item with role: "last_frame". The documented limits allow one first-frame image and one last-frame image. Describe a plausible transition between them rather than expecting a prompt to reconcile unrelated views automatically.

Image-to-video takes its aspect ratio from the image: the reference says the ratio is always treated as adaptive. If a layout matters, prepare the source composition accordingly instead of relying on a conflicting landscape or portrait setting.

Use references when you want to guide a new shot

Reference-to-video can combine reference images, video and audio. An authored example might use a product image alongside a clip showing the desired kind of camera movement:

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "Create a new desk scene featuring the lamp in the reference image. Use the reference clip to guide a slow camera move, with soft afternoon lighting."},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/your-lamp-reference.jpg"},
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {"url": "https://example.com/your-camera-reference.mp4"},
      "role": "reference_video"
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "16:9"
}

The addresses are placeholders, and the prompt expresses the intended use of each reference. It is not evidence of a generated result or a promise of exact motion transfer.

For reference-to-video, ratio may be omitted to use adaptive, or set to a supported concrete value. For audio, use an audio_url item with role: "reference_audio". Video and audio inputs belong to this reference scenario, rather than first/last-frame generation.

Keep reference roles separate from frame roles. Once you include a reference_image, reference_video or reference_audio, do not also send first_frame or last_frame. If you need a fixed opening image, return to the frame example and remove the references. If the material should guide a fresh composition, keep the reference example and remove the fixed frame.

Prepare assets before submitting

The same H3 reference sets different limits for each asset type:

Asset	Formats and size	Count and duration
Images	JPG/JPEG, PNG, WEBP, HEIC, HEIF; up to 30 MB each	Up to nine reference images, or one first frame and one last frame in frame mode
Video references	MP4/MOV, H.264/AVC or H.265/HEVC video, AAC or MP3 audio; up to 50 MB each	Up to three; 2–15 seconds per clip and at most 15 seconds combined
Audio references	WAV/MP3; up to 15 MB each	Up to three; 2–15 seconds per file and at most 15 seconds combined

Images and videos must have width and height between 256 and 5760 pixels and an aspect ratio between 0.4 and 2.5. Reference videos also need 23.976–60 fps. The total request body must stay within 64 MB; the documentation recommends public URLs for large files and avoiding Base64 when possible. An allowed source-file size is not permission to embed every large asset into one oversized request.

Check that a URL returns the intended asset without your browser session. A page containing a preview, a local file path, and a retrievable media URL are different inputs. The source document describes other asset forms, but the examples here deliberately use public URLs so that the required files are visible in the request.

Submit the input you selected

After configuring an authorized account and key through the Tokenhot Quick Start, save one complete example as request.json in a new private job folder. Set TOKENHOT_API_KEY in your environment. With Bash and a recent cURL, submit once:

curl --silent --show-error --fail-with-body --max-time 120 \
  --request POST 'https://api.tokenhot.ai/v1/video/generations' \
  --header "Authorization: Bearer ${TOKENHOT_API_KEY:?Set TOKENHOT_API_KEY first}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  --output submission.json

The creation documentation's response example contains a top-level task_id. Preserve it with the request and response. A task ID records a submitted job; it is not a playable video. If submission times out, establish whether a job exists before sending another potentially billable request.

Before relying on the result in an application, confirm the H3-applicable task-query endpoint, statuses and result fields with the service. The adjacent Hailuo query page does not explicitly identify H3, so this guide does not borrow its host or response parser, or substitute the Wan polling contract. That is the remaining integration step after selecting and submitting the input.

The useful choice comes first: are you inventing a scene, animating a specified frame, or guiding a new shot with references? Choose that job, then let its roles and aspect-ratio rules shape the request.