--- title: "Produce a video from reference images and videos with MiniMax H3" method: POST path: "/v2/video/edit/minimax-h3-reference-to-video" tags: ["video-edit"] --- # Produce a video from reference images and videos with MiniMax H3 `POST /v2/video/edit/minimax-h3-reference-to-video` Produce a video from a text prompt and reference media with MiniMax H3. The prompt addresses the references by position: the first reference image is `Image 1`, the second `Image 2`, the first reference video is `Video 1`, and so on. Supply reference images either as `reference_image_asset_identifiers` (images already stored with Ideogram) or as raw `reference_images` bytes (multipart requests only); supplying both is rejected, and uploaded bytes are used for this request only and are not stored as an asset. Supply reference videos as `reference_video_asset_identifiers`, which must reference videos generated with Ideogram. At most 9 reference images and 3 reference videos are accepted, and reference videos are capped again on clip length. References are optional. With none, the video is produced from the prompt alone. Video generation always runs asynchronously: the response returns as soon as the request is accepted and carries only a `generation_id`. Poll for completion and results with `GET /v1/generations/{generation_id}` using that id, or supply a `webhook_url` to have the finished result POSTed to your server instead. Video links are available for a limited period of time; download the video if you want to keep it. ## Request body - EditVideoMinimaxH3ReferenceToVideoRequest — Request body for MiniMax H3 reference-to-video. The prompt addresses references by position — `Image 1`, `Video 1`, and so on. Reference images arrive either as `reference_image_asset_identifiers` or (multipart requests only) as raw `reference_images` bytes, never both. Reference videos arrive only as `reference_video_asset_identifiers`, which must reference videos generated with Ideogram. Every reference is optional. - `prompt` string, required — A natural-language prompt describing the video to produce. Reference media is addressed by position, as in "Image 1 walks toward the camera with the motion of Video 1". - `reference_image_asset_identifiers` AssetIdentifier[] — Images already stored with Ideogram to use as references, by reference, in prompt order. Cannot be combined with `reference_images`. Only image assets are accepted. - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required - `asset_id` string, required - `reference_images` string[] — Images to use as references (max size 50MB each), as raw bytes, in prompt order; only common image formats such as JPEG, PNG, and WEBP are supported. Multipart requests only. Cannot be combined with `reference_image_asset_identifiers`. The bytes are used for this request only and are not stored as an asset. - `reference_video_asset_identifiers` AssetIdentifier[] — Videos generated with Ideogram to use as motion references, by reference, in prompt order. Each clip must be between 2 and 15 seconds long, and the clips must total no more than 15 seconds. Raw video uploads are not accepted. - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required - `asset_id` string, required - `aspect_ratio` '21x9' | '16x9' | '4x3' | '1x1' | '3x4' | '9x16' — The aspect ratio of the generated video. - `resolution` '480p' | '768p' | '2k' | '4k' — The resolution tier of the generated video. `480p` and `768p` are generated natively; `2k` and `4k` are upscaled from a `768p` result. Higher tiers cost more. - `duration` integer — The length of the generated video in seconds. - `prompt_expansion_mode` 'disabled' | 'fast' | 'balanced' | 'quality' — How much the model may rewrite the prompt before generating. `disabled` uses the prompt as written; the other modes trade latency for a richer rewrite. - `webhook_url` string, uri — HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a JSON POST to this URL once all images for the request have finished generating. The body mirrors the synchronous generate response: `request_id`, `created`, and a `data` array containing every generated image (`url`, `prompt`, `resolution`, `seed`, `is_image_safe`). Each delivery is signed with Ed25519 and verifiable against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS; private and loopback hosts and the cloud metadata service are rejected. - `private` boolean, nullable — When true or omitted, the output is kept private to your account. Set to false to publish the output to the public feed. Enterprise accounts always generate privately. - `target_collection_id` string — A collection you can write to, by its URL-safe base64 collection id. The output videos are added to it when the request completes. ## Response `200` An acknowledgement to poll with `GET /v1/generations/{generation_id}`. - GenerateVideoMinimaxH3Response — Acknowledgement returned by the MiniMax H3 video generation endpoints. Video generation always runs asynchronously, so the generated video is never part of this response: poll for it with `GET /v1/generations/{generation_id}` using the returned `generation_id`, or receive it at the `webhook_url` you supplied. - `generation_id` string, required — URL-safe base64 ID of the accepted generation. Accepted by the `GET /v1/generations/{generation_id}` polling endpoint. - `created` string, date-time, required — The time the request was accepted. ## Other responses - `400` — Invalid input provided. - `401` — Unauthorized. - `402` — Insufficient credits or quota. - `403` — This account does not have access to this model. - `404` — A referenced asset was not found. - `422` — The prompt did not pass safety checks. - `429` — Too many requests. - `500` — Internal server error. - `503` — The endpoint is temporarily unavailable. ## Changes - **2026-09-05** `c0e3105ea651` — 1 info - endpoint added [Change history](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/changes/v2/video/edit/minimax-h3-reference-to-video/post.md) --- [API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/revisions/185ac0b0801d?raw)