Minimax H3 Controlnet Union API Documentation

Minimax H3 Controlnet Union API Documentation

Playground

MiniMax H3 Open Weights ControlNet Union generates a new video that follows the motion and composition of a source video. Pose, depth, edges, lines, scribble or grayscale structure is extracted from the source automatically and guides the output, optionally with reference images for the subject or style, with native stereo audio generated in the same pass. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

MiniMax H3 ControlNet Union Open Weights generates a new video while following the motion, structure, and composition of a source video. The model automatically extracts the selected control signal — such as pose, depth, edges, lines, scribble, or grayscale structure — so you can guide generation with a normal source video instead of preparing control maps manually.

Use pose for motion and character-performance transfer, depth for preserving spatial layout and camera movement, edge-based controls for structural restyling, or gray for recoloring and relighting. Optional reference images and audio can provide additional subject, style, or sound guidance.

Why Choose This?

• Seven control types in one model
  Choose pose, depth, canny, soft_edge, lines, scribble, or gray depending on what should be preserved from the source.

• Automatic control extraction
  Upload a normal source video and let the model derive the selected control signal automatically.

• Character motion transfer
  Combine pose with reference images to generate a different character performing the source video’s motion.

• Structure-preserving restyling
  Use depth or edge controls to change the visual style, environment, or subject while retaining source composition and movement.

• Recoloring and relighting
  Use gray to preserve luminance structure while changing color, lighting, or overall grading.

• Multimodal reference guidance
  Add up to 9 reference images and 3 reference audio inputs for additional subject, style, or sound control.

• Generated or preserved audio
  Generate native audio with the new video, or disable audio generation to preserve the source soundtrack.

• Four resolution tiers
  Generate at 480p, 540p, 768p, or 1080p.

Parameters

Choosing a Control Type

How to Use

1. Upload a source video — Provide the footage whose motion or structure should guide the new result.
2. Choose a control type — Select the source information you want to preserve.
3. Write the prompt — Describe the new subject, scene, appearance, style, lighting, and audio direction.
4. Add reference images optional — Supply visual references when subject identity or style needs additional guidance.
5. Add reference audio optional — Provide audio references when sound direction matters.
6. Adjust control strength optional — Lower the value for more freedom or increase it for stronger source adherence.
7. Choose resolution — Select 480p, 540p, 768p, or 1080p.
8. Configure audio — Keep generate_audio=true for newly generated audio, or disable it to preserve the source soundtrack.
9. Set seed optional — Use a fixed seed when reproducibility is needed.
10. Submit — Generate the controlled video.

Pricing

Pricing is based on the processed source-video duration and selected resolution, plus any reference-image or reference-audio charges.

Source duration is rounded up to the next whole second, with a minimum billed duration of 3 seconds and a maximum of 15 seconds.

Reference Pricing

control_type, control_strength, generate_audio, prompt, and seed do not add separate charges.

Example Costs

For source videos longer than 15 seconds, only the first 15 seconds are processed and billed.

Best Use Cases

• Character animation — Transfer body and performance motion to a different character using pose.
• Dance and performance transfer — Recreate choreography or gestures while changing the performer.
• Scene restyling — Change environments, visual styles, or subjects while retaining source structure.
• Camera-motion preservation — Use depth to keep spatial layout and camera movement while rebuilding the scene.
• Architecture and product workflows — Use lines or edge controls to preserve geometric structure.
• Recoloring and relighting — Use gray to retain brightness structure while changing color and lighting.
• Creative video transformation — Combine source-video control with image and audio references for more directed generation.

Pro Tips

• Use pose with a clear full-body reference image when transferring human motion to another character.
• Source videos with the full subject visible make pose-based control easier to follow.
• Use depth when camera movement and spatial layout matter more than exact surface details.
• Use canny for stronger structural adherence and soft_edge when you want more creative freedom.
• Lower control_strength when the prompt should have more influence.
• Increase control_strength when the result drifts too far from the source structure.
• Use generate_audio=false when the original soundtrack should remain unchanged.
• Use 480p for lower-cost testing before moving to higher resolutions.

Notes

• prompt and video are required.
• Up to the first 15 seconds of the source video are processed.
• Output duration follows the processed source-video duration.
• Output aspect ratio follows the source video.
• control_type defaults to pose.
• control_strength defaults to 1.
• reference_images supports up to 9 images.
• reference_audios supports up to 3 inputs.
• resolution defaults to 480p.
• generate_audio defaults to true.
• When generate_audio=false, the source video soundtrack is preserved.

Related Models

• MiniMax H3 Video Edit Open Weights — Edit an existing video using natural-language instructions.
• MiniMax H3 Reference-to-Video Open Weights — Generate videos with image, video, and audio reference guidance.
• MiniMax H3 Image-to-Video Open Weights — Animate a first-frame image with prompt-guided motion and audio.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "control_type": "pose",
  "control_strength": 1,
  "resolution": "480p",
  "generate_audio": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/minimax-h3/controlnet-union" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters