Head Swap API for Developers
Head Swap API
Integrate AI head swap into your app in minutes. Replace full heads in photos with a simple REST API. SDKs for Python, Node.js, Go, and Rust.
Free to start
No watermarks on paid plans
Subscription or usage-based
Auto-scaling
Trusted by teams at
Everything You Need to Ship Head Swap
One API for full-head replacement in photos. Fully managed infrastructure, multi-language SDKs, and production-ready outputs.
Full Head Replacement
Replace the entire head region instead of only the face. Ideal for changing identity, angle, or hairstyle while keeping the original body and scene.
Automatic Alignment
AI matches head angle, position, and lighting for natural blending with fewer visible seams or mismatched edges.
Fast Image Processing
Generate head swaps in seconds with predictable per-image pricing and production-ready image jobs.
Platform-Ready Formats
Create outputs ready for social posts, thumbnails, profile photos, ads, and web use across common aspect ratios.
Auto-Scaling Infrastructure
Scales compute to match demand — handles traffic spikes automatically. Scales to zero when idle. No GPU provisioning.
Commercial-Ready
Paid plans support non-watermarked outputs with commercial licensing. Suitable for creator tools, marketing workflows, entertainment apps, and photo editors.
Integrate in 3 Steps
From zero to head swapping in production — no GPU setup, no model deployment, no infrastructure headaches.
1
Get Your API Key
Sign up at magichour.ai, open the Developer page to generate your API key, and start making requests. Free credits on signup let you test the API.
2
Make Your First Request
Upload a base (body) photo and a head photo, then POST to /v1/head-swap with body_file_path and head_file_path pointing at your assets.
3
Get Results & Scale
Retrieve the blended image from the job response or your usual polling flow. Deploy to production — infrastructure scales automatically.
Code Examples
Head Swap in a few lines of code. Install an SDK or use the REST API directly.
from magic_hour import Client
from os import getenv
client = Client(token=getenv("MAGIC_HOUR_API_KEY"))
res = client.v1.head_swap.generate(
name="Head swap",
max_resolution=1024,
assets={
"body_file_path": "/path/to/body.png",
"head_file_path": "/path/to/head.png",
},
)SDKs for Every Stack
Official open-source SDKs with full TypeScript/type support. Install and start building.
Head Swap API Pricing
Subscription plans for standard usage.
Prefer usage-based pricing?
Email us or message us in Intercom and we will set up your usage-based pricing.
API Calculator
Use our calculator to estimate your API costs.
Tier
Estimated monthly cost
$1.73
Based on 24 FPS
Built for Builders
See how developers use the Head Swap API to power real products.
Creator Tools & Content Apps
Let users place themselves into poses, scenes, and body-first creator formats without reshoots. Great for remix apps, meme tools, and creator workflows.
Marketing & Ad Personalization
Create localized campaign variants by swapping in new heads while keeping the original body language, framing, and composition.
Profile & Team Photos
Fix otherwise great photos by replacing a poorly angled head, outdated hairstyle, or closed-eye capture without reshooting.
Entertainment & Fan Content
Place users into celebrity, movie, and sports scenes while preserving the original body pose and visual context.
Photo Editing Platforms
Add head swap as a premium editing feature inside photo apps, creative suites, and AI editing workflows.
Thumbnails & A/B Tests
Generate multiple variations quickly for thumbnails, social posts, campaign tests, and editorial experiments.
Try before integrating
Try Head Swap Free — No Code Required
Test quality first with the free tool, then plug the same output quality into your app with the API when you are ready.
Head Swap API — Frequently Asked Questions
Magic Hour's Head Swap API is a RESTful API that lets developers replace full heads in photos with AI. It is designed for cases where swapping the entire head works better than face-only replacement.
The Head Swap API supports photos (JPG, PNG, WebP). Upload a base photo and a head photo; receive a new image with the head blended into the original scene.
Sign up at magichour.ai, navigate to the Developer page to generate your API key, and start making requests. You get free credits on signup to test the API.
Magic Hour offers subscription plans for predictable monthly usage, plus usage-based pricing for higher-volume teams. Use the calculator on this page for estimates.
Official SDKs for Python, Node.js (TypeScript), Go, and Rust. All SDKs are open source on GitHub and support the full API surface.
Head swap replaces the entire head region, which is useful for changing angle, hairstyle, or overall head shape while keeping the body and scene. Face swap focuses more tightly on facial features.
Head swap jobs typically complete in a few seconds per image depending on resolution and queue load.
Yes. Infrastructure scales compute up automatically. No rate limits on paid plans. Scales to zero when idle — no paying for idle GPUs.
Paid API plans support non-watermarked outputs. Free or trial usage may include watermarks; teams upgrade to paid for production.
Generated outputs are temporarily stored for download and then automatically deleted. Input files are not retained. Magic Hour does not use your data to train models.
Yes. Magic Hour offers a free head swap tool at magichour.ai/products/head-swap where you can test quality with your own photos.