Minimax H3 Image Edit API Documentation

Minimax H3 Image Edit API Documentation

Playground

MiniMax H3 Image Edit enables precise image editing and multi-image composition with up to 16 reference images, supporting flexible creative workflows and high-resolution output. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

MiniMax H3 Image Edit edits and combines images from 1–16 reference images using text instructions. Describe the desired changes and refer to each input image by its order when multiple references are used.

Why Choose This?

• Multi-reference editing — Use up to 16 images in a single editing workflow.

• Natural-language instructions — Describe edits and refer to inputs as image 1, image 2, and so on.

• Up to 4K output — Choose 1k, 2k, or 4k.

• Flexible framing — Select an aspect ratio or leave it empty for automatic selection.

• Multiple output formats — Export as PNG, JPEG, or WebP.

Parameters

How to Use

1. Upload reference images — Provide between 1 and 16 images.
2. Write an edit instruction — Describe the desired changes and identify images by number when needed.
3. Choose framing optional — Select an aspect ratio or leave it empty for automatic selection.
4. Choose resolution — Select 1k, 2k, or 4k.
5. Choose output format optional — Select PNG, JPEG, or WebP.
6. Submit — Generate and retrieve the edited image.

Pricing

Pricing is based on the selected output resolution and the number of input images.

Each input image costs $0.008.

Example Costs

1k and 2k use the same output price.

Aspect ratio and output format do not add separate charges.

Best Use Cases

• Multi-image composition — Combine subjects, objects, or visual elements from several references.
• Portrait editing — Adjust clothing, environment, styling, or composition.
• Product editing — Use multiple references to guide product presentation and scene changes.
• Background changes — Place existing subjects into different environments.
• Advertising concepts — Create image variations for campaign and promotional workflows.
• High-resolution editing — Generate edited outputs at up to 4k.

Pro Tips

• Describe both the requested change and any important elements that should remain consistent.
• Refer to images by number when multiple references are used.
• Keep the role of each reference clear in the instruction.
• Use 2k when you need a larger output than 1k at the same output price.
• Use fewer references when several images provide conflicting guidance.

Notes

• prompt and images are required.
• images supports between 1 and 16 inputs.
• Supported input formats are JPG, PNG, WEBP, HEIC, and HEIF.
• Each image side must be between 128 and 8192 pixels.
• Leaving aspect_ratio empty allows automatic output framing.

Related Models

• MiniMax H3 Image Text-to-Image — Generate images 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",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "output_format": "png"
}
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-image/edit" \
  -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