MiniMax H3 Character Replace API

Send a person photo and a guide video with model: minimax-h3-swap to POST /api/v1/videos/generations. The main person in the video takes on the face, hair, body and outfit from the photo, while the scene, camera motion, movement and audio track stay as they were. Output is 720p and follows the guide video's length and aspect ratio.
Get API Key
Dancer on an empty stage with a translucent second silhouette overlapping in the same pose

New Person, Same Shot

Photo in, person replaced

image_url is the person photo (up to 10 MB). A clear, front-facing half-body or full-body photo of a single person works best. Without swap_details, the photo is described automatically to transfer the outfit.
Portrait photo pinned beside a monitor showing a person walking down a street

Pick the right person in a group

In videos with several people, set swap_target by position or action, such as "the man on the left" or "the player kicking the ball", not by clothing. Logos, watermarks and text in the original frame are kept as-is.
Football players on a pitch with one player highlighted by a soft rim of light

Length follows the guide video

By default the output matches the guide video rounded down to whole seconds, so 14.6 seconds gives 14. Videos must be at least 5 seconds; for clips longer than 15 seconds pass duration to render only the first 5 to 15 seconds.
Film strip on a light table with a section marked off by two clips
image_url and video_url are required; the rest refine which person changes and how much of the video is used.

MiniMax H3 Character Replace Request Fields and Limits

image_url (required)

Public URL of the person photo, up to 10 MB. This person replaces the main person in the video.

video_url (required)

Public URL of the guide video, up to 100 MB, at least 5 seconds. Videos longer than 15 seconds are rejected unless duration is set.

duration

Optional integer from 5 to 15. Renders only the first N seconds and must not exceed the actual video length; a longer value is rejected, not clamped.

resolution

480p or 720p (default 720p). The video is always generated at 720p at the same price; aspect ratio follows the guide video.

swap_target

Optional, up to 600 characters. Which person to replace when there are several, described by position or action.

swap_details and callback

swap_details: optional head-to-toe description of the photo's person, up to 800 characters. custom_callback_url: optional public HTTPS URL for status updates.
One rate for every request, billed per second of the generated video.

MiniMax H3 Character Replace API Pricing

2 tokens ($0.04) per second

All output is 720p, so there is a single rate. A 5-second result costs 10 tokens ($0.20).

Billed on output length

Without duration, a 14.6-second guide video produces 14 seconds and costs 28 tokens ($0.56).

Cap the bill with duration

The longest output, 15 seconds, costs 30 tokens ($0.60). Use duration to render a shorter opening section of a long clip.

Refunds on failure

Tokens are deducted when the task is accepted and returned automatically if the generation fails. cost in the response is the amount actually charged.

Integrate the MiniMax H3 Character Replace API

1

1. Create an API key

Generate it at /keys and call the API from your server with Authorization: Bearer <key>.
2

2. Prepare the inputs

Host a front-facing photo of one person and a guide video of at least 5 seconds. Trim or set duration for anything longer than 15 seconds.
3

3. Submit

POST {"model": "minimax-h3-swap", "image_url": "…", "video_url": "…"} to /api/v1/videos/generations, adding swap_target for multi-person shots. Store img_uuid.
4

4. Fetch the result

Poll GET /api/v1/jobs/detail or use custom_callback_url; download the video before link_expired_at.
Create an API Key
Put a user or a new character into footage that already works.

What Developers Build with MiniMax H3 Character Replace

"Star in this clip" features

Let users upload a selfie and appear in a trending dance, sports moment or movie-style scene.

Ad variants with different talent

Re-cast one approved ad shot with several presenters while keeping the camera work and soundtrack.

Costume and look previews

Show how a person looks in a scene by swapping in a photo that wears a given outfit.

Template video apps

Keep a library of guide videos and generate personalized versions on demand at a fixed per-second price.
Inputs, length, multi-person videos and billing.

MiniMax H3 Character Replace API FAQ

What is kept from the original video?

The scene, camera motion, movement and audio track. Logos, watermarks and on-screen text are also kept.

What output resolution do I get?

Always 720p. 480p is accepted as a value but still renders at 720p for the same price.

How long can the guide video be?

At least 5 seconds. Over 15 seconds is rejected unless you set duration (5 to 15) to use only the first N seconds.

How do I choose who gets replaced in a group shot?

Set swap_target to a position or action, for example "the person in the center of the frame".

How much does it cost?

2 tokens ($0.04) per second of output: 10 tokens ($0.20) for 5 seconds, up to 30 tokens ($0.60) for 15 seconds.

What photo works best?

A clear, front-facing half-body or full-body photo of a single person.

Start Building with the MiniMax H3 Character Replace API