Face Swap API for Developers
Face Swap API
Integrate AI face swap into your app in minutes. Swap faces in photos, videos, and GIFs with a simple REST API. SDKs for Python, Node.js, Go, and Rust.
Free credits on signup
Transparent per-credit pricing
No watermarks with paid plans or credit packs
Subscriptions, credit packs, or usage-based billing
Auto-scaling
Iron Man
Film Noir
Home Drama
Action Thriller
Sunset Romance
Horror Moment
Office Western
Trusted by teams at
Everything You Need to Ship Face Swap
One API for photos, videos, and GIFs. Fully managed infrastructure, multi-language SDKs, and commercial-ready outputs.
Photo Face Swap
Swap faces in any photo with a single API call. Supports JPG, PNG, and WebP with automatic face detection and natural blending.
Video Face Swap
Process full videos frame-by-frame. Handles motion, angles, and lighting changes. Trim to specific segments with start/end timestamps.
Multi-Face Swap
Detect and swap multiple faces in one request. Map each face to a different identity or apply the same face to all.
Fast Processing
Photos in 1–5 seconds. Videos optimized for speed with async processing and webhook notifications on completion.
Auto-Scaling Infrastructure
Scales compute to match demand — handles traffic spikes automatically. Scales to zero when idle. No GPU provisioning.
Commercial-Ready
Paid subscriptions and credit-pack purchases support non-watermarked outputs with commercial licensing. Suitable for marketing, SaaS products, entertainment apps, and client work.
Integrate in 3 Steps
From zero to face-swapping in production — no GPU setup; no model deployment; no infrastructure headaches.
1
Get Your API Key
Sign up free and generate an API key from the Developer dashboard. You get free credits to start.
2
Make Your First Request
Install an SDK or call the REST API directly. Send a face image and original photo/video to the face swap endpoint.
3
Get Results & Scale
Receive the output via response or webhook. Deploy to production — infrastructure scales automatically.
Make your first photo face swap
Start with one photo before processing videos or a batch. The source supplies the face; the target supplies the scene.
from magic_hour import Client
from os import getenv
client = Client(token=getenv("MAGIC_HOUR_API_KEY"))
res = client.v1.face_swap_photo.generate(
assets={
"face_mappings": [
{
"new_face": "/path/to/1234.png",
"original_face": "api-assets/id/0-0.png",
}
],
"face_swap_mode": "all-faces",
"source_file_path": "/path/to/1234.png",
"target_file_path": "/path/to/1234.png",
},
name="Face Swap image",
wait_for_completion=True,
download_outputs=True,
download_directory="."
)
from magic_hour import Client
from os import getenv
client = Client(token=getenv("MAGIC_HOUR_API_KEY"))
res = client.v1.face_swap.generate(
assets={
"face_mappings": [
{
"new_face": "/path/to/1234.png",
"original_face": "api-assets/id/0-0.png",
}
],
"face_swap_mode": "all-faces",
"image_file_path": "image/id/1234.png",
"video_file_path": "/path/to/1234.mp4",
"video_source": "file",
},
end_seconds=15.0,
start_seconds=0.0,
name="Face Swap video",
style={"version": "default"},
wait_for_completion=True,
download_outputs=True,
download_directory="."
)Before you run
- Create an API key and add it to the authorization value shown in your chosen snippet.
- Provide source and target images you control. Use a clear face and get permission from the people shown. For web-hosted inputs, use direct HTTPS file URLs. For private or local files, upload the file first and use its returned
file_path. - Choose Python, Node.js, or HTTP above, then review the example before running it. The Face Swap example demonstrates both the photo and video endpoints, so a full fresh run submits two billable jobs.
Choose the endpoint that matches your target media. For a single image, use the photo face-swap workflow. For a video clip, follow the video face-swap API guide. Test with your own source face and target media before scaling your integration.
Expected result and async processing
The POST returns a project id and credits_charged, not the finished media. Save the project ID and poll it with backoff until the status is complete, error or canceled. For completed jobs, read the final credit charge, download URL and expiration time. Handle errors and cancellations without continuing to poll. Download your output before the URL expires; if it expires, retrieve the project again for a fresh URL.
Stopping a poll does not cancel the job or prove failure. Reuse the saved project ID to resume polling without creating another job. If the create request times out before returning an ID, do not submit it again. Email support@magichour.ai with the endpoint, request name and UTC timestamp so the request can be traced first. For production, use webhooks, verify signatures and handle repeated deliveries. Poll for cancellation because canceled jobs do not emit a cancellation webhook. See measured processing times; queue load, input and settings affect latency.
Pricing and usage estimates
Photo and video face swap have different credit costs. This example includes one request for each endpoint. Read each completed project for its exact charge; the calculator below estimates supported monthly video workloads. These are usage-based billing examples, not subscription prices or a promise of free generation. Usage-based billing requires setup assistance. Subscription and credit-pack economics differ. Video create charges are estimates; read the completed project for the final charge.
Troubleshooting
- 401: verify the API key and Bearer header. Keep keys in server environment variables.
- Invalid input: use direct file URLs or uploaded paths, check the response message and compare the payload with the endpoint schema. Photo requests use source_file_path and target_file_path; they do not use face_file_path.
- Insufficient balance or plan access: inspect the error code and account balance and tier. A free key does not unlock every model.
- 429 or transient polling failure: reduce concurrency, back off and resume the existing project ID. Do not blindly retry a create request.
- Unexpected output: use a front-facing source face with fewer obstructions. Use face detection and individual mappings when each target face needs a different identity.
Continue with the bulk Face Swap guide when you are ready to turn this first request into a repeatable workflow.
Get an API key and run your first request →Estimate Your API Costs
Every generation uses credits. Prepay with a subscription or one-time credit packs, or request usage-based billing for monthly invoicing and volume discounts.
Pricing tier options
Seconds of Video Per Month
100 seconds
seconds
Recommended plan
Creator Yearly
$144
/year
144,000 credits per year
Up to 1.7 hours of video
Up to 14,400 images
PRO YEARLY covers your usage
- 12,000credits / month
- 25,000credits / month
- 13,000credits / month
Estimated usage
Included
Remaining headroom
TOTAL BILL
$300
/year
SDKs for Every Stack
Official open-source SDKs with full TypeScript/type support. Install and start building.
Face Swap API Pricing
Subscription plans for standard usage.
Need usage-based billing?
Email us or message us in Intercom for monthly billing with graduated volume discounts.
Built for Builders
See how developers use the Face Swap API to power real products.
Social & Entertainment Apps
Add face swap features to social platforms, meme generators, dating apps, and entertainment products. Drive engagement and virality with personalized content.
E-Commerce & Virtual Try-On
Let customers see themselves wearing products. Swap faces onto model photos for personalized shopping experiences that increase conversion.
Marketing & Ad Personalization
Create localized ad variations at scale. Swap talent faces for different markets, generate UGC-style content, and A/B test creative without reshoots.
Content Creation Platforms
Power video editing tools, thumbnail generators, and content automation workflows. Let creators produce more variants without manual editing.
Gaming & Avatars
Generate personalized game characters, avatars, and in-game content by swapping player faces onto character models.
Education & Training
Create personalized training videos, educational content with character customization, and interactive learning materials.
Try before integrating
Try Face 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.
Face Swap API — Frequently Asked Questions
Magic Hour's Face Swap API is a RESTful API that lets developers integrate AI-powered face swapping into any application. It supports photo, video, and GIF face swaps with realistic results. You authenticate with an API key and make simple HTTP requests — or use our official SDKs for Python, Node.js, Go, and Rust.
The Face Swap API supports photos (JPG, PNG, WebP), videos (MP4, MOV), and GIFs. For video, you can specify start and end timestamps to process specific segments. Multi-face detection and swapping is supported across all formats.
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. Install an SDK (pip install magic-hour, npm install magic-hour, etc.) or call the REST endpoints directly. Full documentation and code examples are available at docs.magichour.ai.
Magic Hour offers subscription plans starting at $19/month (Creator), $39/month (Pro), and $99/month (Business), each including a monthly credit allotment. Credits are consumed per generation based on output length and model. One-time credit packs add credits without a subscription. Usage-based billing with graduated volume discounts is available by request. A free tier with credits is available on signup — no credit card required.
Magic Hour provides official SDKs for Python, Node.js (TypeScript), Go, and Rust. All SDKs are open source on GitHub and support the full API surface including face swap, image-to-video, text-to-video, animation, and more. You can also call the REST API directly from any language that supports HTTP.
Yes. The API automatically detects all faces in the source media. You can swap one, several, or all faces in a single API call. Each face can be mapped to a different target identity for precise control over multi-face swaps.
Photo face swaps typically complete in 1–5 seconds. Video processing time depends on duration and resolution but is optimized for speed. The API is asynchronous for video — you submit a job and poll for completion or receive a webhook callback when done.
Yes. Magic Hour's infrastructure scales compute up automatically to handle demand spikes, with no API rate limits or concurrency limits. When you have zero traffic, it scales to zero, so you do not pay for idle GPUs.
Paid API plans and credit-pack purchases support non-watermarked outputs. Free or trial usage may include watermarks depending on plan settings, so teams usually purchase a plan or credit pack for production and commercial delivery.
Generated outputs are temporarily stored for download and then automatically deleted. Input files are not retained after processing. Magic Hour does not use your data to train models.
Yes. Magic Hour offers a free face swap tool at magichour.ai/products/face-swap where you can test the quality with your own photos and videos — no sign up required. Once you're satisfied with the results, integrate the same technology via the API.
Magic Hour is the only face swap API backed by a full consumer product with millions of users, proving the technology works at scale. Key differentiators: (1) free try-before-you-buy via the web tool, (2) SDKs in 4 languages, (3) photo + video + GIF in one API, (4) fully managed infrastructure with auto-scaling, (5) Y Combinator-backed company with dedicated support.
Sign up at magichour.ai/developer — no credit card required. You'll receive free credits and an API key immediately. The key works across all Magic Hour API endpoints including Face Swap. Start making API calls in minutes using our Python, Node.js, Go, or Rust SDKs.
New accounts get free credits to test supported free-tier API endpoints. Some models and resolutions require a paid plan; check the current endpoint page and pricing before integrating.