What a face swap API does
A face swap API takes two images and returns a new one. The source image shows the face you want to use. The target image is the photo you want to change. The API finds the face in the target, replaces it with the face from the source, and blends skin tone, light and angle so the result looks like one photo.
Developers use it for things like personalised greeting cards, "put yourself in the poster" campaigns, avatar and profile tools, game characters and photo booth apps at events. Instead of training and hosting your own models, you send one HTTP request and get an image back.
Before you start
You need three things:
- A Morfran account. New accounts get 50 free credits, enough for ten single face swaps.
- An API key. Create one in your dashboard under API keys. Keep it on your server and never put it in browser or mobile app code.
- Two public image URLs. JPG, PNG or WebP. The source should show one clear face, looking roughly at the camera.
Every request sends the key in the X-API-Key header. The base URL is https://api.morfran.com.
Your first face swap with curl
curl -X POST https://api.morfran.com/v1/face-swap \
-H "X-API-Key: $MORFRAN_KEY" \
-H "Content-Type: application/json" \
-d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'
By default the call is synchronous: the API waits for the result (up to about 60 seconds) and returns a JSON response with a link to the finished image on cdn.morfran.com, plus the credits used. Download the image right away, because results are deleted after one hour.
The same request in JavaScript (Node.js)
const res = await fetch("https://api.morfran.com/v1/face-swap", {
method: "POST",
headers: {
"X-API-Key": process.env.MORFRAN_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
SourceImageUrl: "https://example.com/face.jpg",
TargetImageUrl: "https://example.com/photo.jpg",
}),
});
const data = await res.json();
console.log(res.status, data);
Run this on your server, not in the browser, so your key stays private.
The same request in Python
import os
import requests
res = requests.post(
"https://api.morfran.com/v1/face-swap",
headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
json={
"SourceImageUrl": "https://example.com/face.jpg",
"TargetImageUrl": "https://example.com/photo.jpg",
},
timeout=90,
)
print(res.status_code, res.json())
Long jobs: use async mode
If your app should not wait on an open request, add ?async=true to the URL. The API answers at once with a task id. Then read the result with GET /v1/face-swap/{taskId} every few seconds until it is finished. This works well behind a job queue, or when your own server has a short request timeout.
Group photos: swap up to eight faces
For a team photo or a family picture, use POST /v1/face-swap/group. It changes up to eight faces in one call; MaxFaces sets the limit. A group swap costs 10 credits, a single swap 5 credits. The full list of fields is in the API documentation and the OpenAPI schema.
Handle errors and credits
- 401: the API key is missing or wrong. Check the
X-API-Keyheader. - 402: not enough credits. Buy a credit pack in your dashboard.
- 422: no face was found. Ask the user for a clearer photo with one face.
Failed requests are not charged. Credits are only taken for finished images, so a retry after a 422 does not cost twice. You can read your balance at any time with GET /v1/credits/balance, which is free.
Tips for better results
- Use a clear source face. One person, facing the camera, eyes open, no sunglasses, good light.
- Match the angle. A face looking straight ahead blends best into a target where the person also looks roughly at the camera.
- Keep faces large enough. A face that is only a few pixels wide in the target cannot be swapped well.
- Similar light helps. A face shot in daylight looks most natural in a daylight target photo.
- Test with your real images. Spend a few of the free credits on photos like the ones your users will upload.
Consent and privacy
Only swap the face of someone who has agreed to it. Do not use a face swap to deceive people, to impersonate someone or to make content that harms a real person. If you publish results, label them as AI generated. Uploaded images and results are deleted from our storage within one hour, and we do not use them to train AI models. Misuse can be reported through the contact page and is handled within 48 hours.
Use it from an AI agent
The same face swap is available on Morfran's MCP server at https://api.morfran.com/mcp, so assistants such as Claude can call it with your API key. Setup is described in the MCP section of the docs.
Questions
How much does the face swap API cost?
A single face swap costs 5 credits and a group face swap (up to eight faces) costs 10 credits. New accounts get 50 free credits. After that you buy credit packs; there is no subscription. See pricing for the packs.
How long does a face swap take?
Most results come back within the synchronous wait of about 60 seconds. For long jobs or short server timeouts, use ?async=true and read the result with the task id.
Can I send images as base64 instead of URLs?
The examples here use public URLs, which is the simplest way. The OpenAPI schema lists every input field the endpoint accepts.
How long are results stored?
Uploaded images and results are deleted within one hour. Save the result image on your side as soon as you receive it.
Can I try it without writing code?
Yes. Sign in and open the Playground. It runs the same face swap in the browser and shows the matching API request.