Head Swap Tool - Magic Hour Docs

​

Overview

​

How It Works

1. Upload a body image - Choose the photo that keeps its body, pose, and scene
2. Upload a head image - Provide the head you want to place on the body
3. Set an optional limit - Use max_resolution to cap the output’s larger dimension
4. Create the job - Submit both file paths to the API
5. Download the result - Poll until complete and retrieve the generated image

​

Use Cases

• Portrait fixes - Replace an unsuitable head angle or expression in an otherwise useful photo
• Creative remixes - Put a different head into an existing composition
• Profile concepts - Explore portrait and character variations without a reshoot
• Content variants - Create alternate thumbnails, posts, or campaign images
• Previsualization - Test identity and styling combinations before production

​

Best Practices

• Use clear, high-resolution inputs - Keep facial features and the full head visible
• Avoid obstructions - Hair, hands, hats, and cropped heads can make alignment harder
• Match proportions - References with similar framing reduce unrealistic scale differences
• Preserve source detail - Avoid heavily compressed or filtered images
• Use max_resolution intentionally - Omit it for your plan maximum or lower it for faster iteration

​

Code Example

curl --request POST \
  --url https://api.magichour.ai/v1/head-swap \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '
{
  "name": "My Head Swap image",
  "max_resolution": 1024,
  "assets": {
    "body_file_path": "api-assets/id/1234.png",
    "head_file_path": "api-assets/id/5678.png"
  }
}
'

​

Pricing

​

API Reference

​

Related Tools