Image Head Swap API Documentation

Image Head Swap API Documentation

Playground

Instant online AI head & face swap for photos with no watermark, delivering realistic, shareable results in seconds. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

WaveSpeedAI Image Head Swap is an advanced AI model for replacing the entire head (face + hair + outline) of a person in a static image using a reference portrait. It keeps body, pose and background intact while rebuilding a new, realistic head that matches the scene’s lighting and perspective.

🎬 What this model does

• Replaces the full head region of the subject (face, hair, silhouette, accessories)
• Preserves body pose, clothing, background and general composition
• Adapts the new head to scene lighting, color tone and camera angle
• Produces clean, watermark-free outputs ready for editing or publication

⚙️ Why it looks realistic

• Full-head geometry replacement Swaps the whole head contour instead of only facial features, avoiding mismatched hairlines or skull shape.

• Pose and expression preservation Uses the base image to keep head angle, gaze direction and expression consistent with the original shot.

• Lighting and color matching Automatically adjusts skin tone, shadows and highlights so the new head sits naturally in the scene.

• High-resolution blending Seamless edges around neck, hair and accessories, minimizing visible artifacts.

🧾 Inputs and Parameters

Required fields:

• image: Base image whose body, background and composition you want to keep.

• face_image: Reference portrait that defines the new identity/head to be inserted.

Other options:

• output_format: Choose the final image format:

• jpeg

• png

• webp

💰 Pricing

💡 Best Use Cases

• Casting and concept design Test different actors’ heads on the same body or costume for film, TV or advertising pitches.

• Privacy and anonymization Replace real heads with synthetic or authorized identities while keeping scenes and actions intact.

• Photo and key art exploration Quickly iterate on hero posters, thumbnails and cover images with different looks.

• Social media and creator workflows Create stylized or character-based versions of yourself while preserving your original photos’ composition.

📎 Tips and Notes

• Use clear, reasonably high-resolution portraits for both image and face_image.
• Try to keep camera angle and approximate lighting similar between the two inputs for best results.
• Avoid heavily occluded faces or extreme motion blur in the base image.
• Always ensure you have the legal right and consent to use all images and likenesses involved in your edits.

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'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "face_image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "output_format": "jpeg"
}
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/wavespeed-ai/image-head-swap" \
  -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