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 that follows the motion and composition of a source video. The control signal - pose, depth, edges, straight lines, scribble or grayscale structure - is extracted from the source automatically, so you only upload a normal video, describe the result, and optionally add reference images for the subject or style. Native stereo audio is generated in the same pass, or the source soundtrack can be kept.

Why Choose This?

• Seven control types in one model
  pose, depth, canny, soft_edge, lines, scribble and gray, all extracted automatically from your video.

• Character animation
  Combine pose with a reference image to make your character perform the motion of the source video.

• Restyle while keeping structure
  Use edges, lines or depth to re-render a clip in a new style, setting or look while keeping its layout and camera movement.

• Recolor and relight
  Use gray to keep the brightness structure and change colors, lighting or grading from the prompt.

• Native audio or preserved audio
  Generate new audio, or set generate_audio to false to keep the source video’s soundtrack.

Parameters

Choosing a Control Type

Pricing

Cost = per-second rate × source video seconds + $0.02 per reference image or reference audio.

Source video seconds are rounded up, with a minimum of 3 and a maximum of 15 (only the first 15 seconds are used). The output has the same duration as the source.

Add-ons: reference image $0.02 each, reference audio $0.02 each. control_type, control_strength, generate_audio, prompt, and seed do not add separate charges.

Worked Examples

Pro Tips

• For character animation, use pose with a clear full-body reference image in reference_images and describe the character in the prompt.
• Source videos with a steady camera and the whole subject in frame give the most accurate pose transfer.
• Lower control_strength when the prompt should change more; raise it when the output drifts from the source.
• Set generate_audio to false to keep the original soundtrack, for example for dance videos.

Notes

• prompt and video are required.
• Up to 15 seconds of the source video are used; the output keeps the source duration and aspect ratio.
• reference_images supports up to 9 images and reference_audios up to 3.

Related Models

• MiniMax H3 Video Edit Open Weights - Edit a video from prompt instructions.
• MiniMax H3 Reference-to-Video Open Weights - Generate video from image, video, or audio references.
• 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