Swap a face in a photo or video
Choose a photo or video API for your source media. Review the face image inputs and selection options before building your upload and preview flow.
AI Face Swap APIs
Integrate face swaps into your app with APIs for photos, videos, and GIFs. Compare single-face, multiple-face, and full-head replacement workflows to choose the right media inputs and face selection method.
Find your API ↓
Choose APIs for your face swap workflow
Map multiple face replacements
Build group photo or video workflows with multiple-face APIs. Use each API's face mapping requirements to connect selected faces to their replacements.
Handle GIFs and full-head swaps
Use the AI GIF Face Swap API for animated input, or a head swap API for full-head replacement. Match each request to the media type and edit your feature needs.
5 API products
IMAGE
AI Photo Face Swap API
Add photo face swapping to your app with a target image URL and a reference face image. Select one face from each input and retrieve the edited image through an asynchronous task.
1 endpoint
VIDEO
AI Video Face Swap API for Clip Workflows
Integrate single-face replacement into your video workflow. Submit a clip and reference face image, select the tracked face to replace, and retrieve the completed video through an asynchronous task.
1 endpoint
IMAGE + VIDEO
AI Multi Face Swap API for Photos and Videos
Add multi-face swapping to your photo and video app. Map each target face to a reference image, with support for up to 20 mappings per photo and four per video.
2 endpoints
IMAGE + VIDEO
AI Head Swap API for Photos and Videos
Integrate head replacement into photo and video editing workflows. Send a target asset with one to four reference images, and use an optional prompt to describe the requested change.
2 endpoints
IMAGE
AI GIF Face Swap API for Animated Images
Add animated face swaps to your app with a GIF and a reference photo. Select the target and reference faces by index, then retrieve the result as an animated GIF.
1 endpoint
What makes VidMage's AI Face Swap APIs stand out
Build face editing around the media and selection your app needs. VidMage offers automatic face detection, explicit face mappings, animated GIF output, and separate head replacement APIs.
Select faces without building the detector
Photo Face Swap handles face detection and cropping; Video Face Swap handles detection and landmark tracking. Both accept referenceFaceImageUrl and optional target and reference indices for one replacement, so your app can specify which face to replace.
Learn more ↗Map each person to a different reference
Use faceMappings for separate replacements: 1 to 20 entries for one photo or 1 to 4 for one video. Each pairs a reference face image with optional target and reference indices. These limits apply to one target asset. Queue separate jobs for additional photos or videos.
Learn more ↗Add GIF swaps and broader head edits
The GIF API returns an edited animation. For broader head edits, separate photo and video APIs accept 1 to 4 referenceImageUrls and an optional customPrompt. A head reference list does not provide the explicit person-to-person mapping of faceMappings.
Learn more ↗Estimate a swap before spending credits
API access requires an active subscription and shares your website credit balance. Photo, video, GIF, and head swaps have separate prices. Check the selected operation's price and use VidMage's read-only MCP capability estimator with its actual inputs before submitting. Estimates consume no credits.
Learn more ↗FAQs
Answers for developers building with AI Face Swap APIs.
Does a face index identify the same person across files?
A face index selects a face in the supplied target or reference media. It is zero-based, and it is not a saved person ID. Keep the selection with its source asset and review it for each new file instead of assuming the detection order will stay the same.
How should my app handle photo, video, and GIF results?
Save the taskId returned by submission and query the same capability until completion. Read imageUrl for photo edits, videoUrl for video edits, or gifUrl for GIF swaps. Configure your result viewer by capability so it can display the completed media in the right format.
Can I send local files, and which upload limits apply?
Use the temporary upload flow for each target or reference input, then pass its returned fileUrl to the matching parameter. Check the selected capability and upload response for current acceptance rules. Consumer website allowances do not establish API file-size, duration, or resolution limits.
What should I do if a face swap request times out?
Keep the original task ID and continue checking that task. If you lost the submission response, recover recent tasks before trying again. Preserve the original idempotency key and follow the returned recovery action so a slow or interrupted request does not become a duplicate submission.
Are the face swap APIs ready for production?
VidMage's Developer APIs are currently in beta and are not yet recommended for production. Test face selection, output quality, billing, and task recovery with your own media. Review the current availability notice before making the API a dependency for a production app.