Minimax H3 Highspeed Reference To Video API Documentation

Minimax H3 Highspeed Reference To Video API Documentation

Playground

MiniMax H3 Highspeed Reference-to-Video generates fast 768P videos from multimodal references with flexible 4-15 second duration, making it suitable for reference-guided character consistency, motion control, creative videos, social content, ads, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

MiniMax H3 Highspeed Reference-to-Video generates videos from multimodal references, including images, video clips, and audio. Use references to guide characters, objects, environments, motion, and sound while generating 4–15 second videos at 768p.

Why Choose This?

• Multimodal reference support — Guide generation with images, videos, and audio.
• Multiple visual references — Use up to 9 reference images and 3 reference videos.
• Optional audio guidance — Add up to 3 audio clips alongside visual references.
• Flexible duration — Generate videos from 4 to 15 seconds.
• 768p output — Generate reference-guided videos at 768p.

Parameters

At least one reference image or reference video must be provided. Audio-only requests are not supported.

How to Use

1. Add visual references — Provide at least one reference image or video.
2. Write a prompt — Describe the desired scene and explain how the references should influence the result.
3. Add audio optional — Supply reference audio when sound or voice guidance is needed.
4. Choose duration — Select an output length from 4 to 15 seconds.
5. Choose framing — Select the desired aspect ratio.
6. Submit — Generate and retrieve the completed video.

Pricing

Reference videos are billed with a 2-second minimum per clip and a 15-second combined maximum. Their combined duration is rounded up to the next whole second. The generated video is charged by the requested duration.

Best Use Cases

• Character consistency — Use reference images to guide recurring people or characters.
• Product videos — Keep products and visual details consistent across generated scenes.
• Motion reference — Use video clips to guide movement and action.
• Audio-guided generation — Add audio references for voice or sound direction.
• Multi-reference storytelling — Combine several references into a single generated scene.

Pro Tips

• Clearly explain the role of each reference in the prompt.
• Use visually consistent references when maintaining a character or product identity.
• Keep reference videos focused on the motion or action you want to guide.
• Start with fewer references when testing a new concept.
• Keep the requested action achievable within the selected output duration.

Notes

• prompt is required.
• Supported aspect ratios are 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. Default: 16:9.
• At least one reference image or video is required.
• Audio cannot be supplied alone.
• Up to 9 reference images are supported.
• Up to 3 reference videos are supported.
• Up to 3 reference audio clips are supported.
• Reference videos longer than the allowed duration are trimmed from the end; short clips are extended to 2 seconds. The combined processed duration is limited to 15 seconds.
• Reference audio clips must each be 2–15 seconds.
• Combined reference audio duration is limited to 15 seconds.
• Use MP4 or MOV reference videos, no larger than 50 MB.
• Reference audio must be WAV or MP3, no larger than 15 MB per file.

Related Models

• MiniMax H3 Highspeed Image-to-Video — Generate videos from a starting image.
• MiniMax H3 Highspeed Text-to-Video — Generate videos directly from text prompts.

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",
  "aspect_ratio": "16:9",
  "resolution": "768p",
  "duration": 5
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/minimax/h3-highspeed/reference-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

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. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

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

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters