MiniMax H3 image-to-video API: frames and reference images

Choose frame control or reference guidance

The vgenv MiniMax H3 API exposes two mutually exclusive image patterns. frame_images controls a first frame, a last frame, or both. reference_images supplies up to nine ordered images that describe identity, product, scene, or visual style without declaring them as timeline endpoints.

Do not send both fields in one request. The service derives the execution mode from the validated image schema and rejects ambiguous combinations instead of silently discarding inputs.

First-frame image-to-video request

Use a public HTTPS image URL or a supported JPEG, PNG, or WebP Data URL. Describe motion, camera behavior, environmental change, and sound in the prompt instead of repeating only what is already visible in the frame.

{
  "model": "minimax/h3",
  "tier": "fast",
  "prompt": "The paper bird takes flight as the camera slowly pushes in",
  "duration": 8,
  "resolution": "768p",
  "aspect_ratio": "16:9",
  "frame_images": [{
    "type": "image_url",
    "image_url": { "url": "https://example.com/first-frame.webp" },
    "frame_type": "first_frame"
  }]
}

Ordered reference-image request

Reference order should match the way your prompt introduces each image. For example, image one can establish product identity while image two establishes lighting. Keep the instruction explicit so the model does not need to infer which visual property matters.

{
  "model": "minimax/h3",
  "tier": "fast",
  "prompt": "Preserve the product from image one and use the studio lighting from image two",
  "duration": 6,
  "resolution": "768p",
  "aspect_ratio": "1:1",
  "reference_images": [
    { "type": "image_url", "image_url": { "url": "https://example.com/product.webp" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/lighting.webp" } }
  ]
}

Input validation and production safety

Each remote image is imported into private storage after URL, network, media-type, signature, and size checks. Public HTTPS URLs must remain reachable during request creation; Data URLs make the create request larger and should be reserved for small controlled inputs.

• Use JPEG, PNG, or WebP and keep each image within 5 MiB.
• Do not place credentials or expiring private tokens in remote image URLs.
• Keep aspect ratio close to the intended output composition.
• Use clear prompt references such as image one and image two.