# Face Swap Pipeline
Put a real person's face into a scene — either a scene generated from your prompt,
or an existing photo you provide. Every result goes through automatic face
restoration, so the swapped face stays sharp and natural.
## How it works
Upload one or two face photos. Then choose one of two directions:
- Generate the scene. Leave Target Photo empty and describe the setting in the
prompt. The scene is created for you, and your face (or both faces) is swapped in.
- Use your own photo. Upload a Target Photo. Nothing is generated; your face is
swapped directly into that photo.
## Modes
| Face Photo 1 | Face Photo 2 | Target Photo | Swap Position | Result |
| --- | --- | --- | --- | --- |
| yes | yes | — | — | A two-person scene is generated from your prompt; both faces are swapped in. Returns 2 images. |
| yes | — | — | — | A single-person scene is generated from your prompt; the face is swapped in. Returns 2 images. |
| yes | yes | yes | — | No generation. Target Photo must contain exactly two people; Face 1 replaces the person on the left, Face 2 the person on the right. |
| yes | — | yes | left / right | No generation. Target Photo must contain exactly two people; only the chosen side is replaced. |
| yes | — | yes | — | No generation. Face 1 is swapped into the Target Photo. A single-person photo is enough here. |
## Requirements for good results
- Face photos should be clear, well lit and front-facing, with the whole face
visible. Sunglasses, heavy shadows and steep angles reduce quality.
- A Target Photo used with Face Photo 2 or with Swap Position must show **exactly
two people, side by side, both faces clearly visible**. Zero, one, or three-plus
detected faces will be rejected — use the single-person mode instead (Face Photo 1
+ Target Photo, nothing else).
- A Target Photo is not a background plate. If you want a scene with no people in
it, leave Target Photo empty and describe the scene in the prompt instead.
## Notes
- Prompt, Output Style, Width and Height only apply when the scene is generated.
They are ignored when a Target Photo is provided.
- Write prompts about the setting — location, outfit, lighting, atmosphere. Facial
features are taken from your uploaded photos, so you do not need to describe them.
- Generated scenes use a fixed seed, so the same prompt and style produce the same
scene each time. Change the prompt or the style to get a different composition.
- Supported input formats: PNG, JPG, JPEG, BMP, WEBP, GIF, TIF, HEIC.
## Common errors
- "Two faces could not be detected" — the photo used for the swap does not contain
two clearly visible faces. With a Target Photo, provide a two-person photo or
switch to the single-person mode. With a generated scene, change the prompt or the
output style so both people are framed clearly.
- "Too many faces detected" — the Target Photo contains more than two faces. Crop
it down to the two people you want, or pick another photo.
- "No face could be detected" — a face photo is too dark, too small, or not
front-facing. Upload a clearer portrait.
- "The given parameter combination is not supported" — Swap Position needs a Target
Photo and cannot be combined with Face Photo 2.
Example prompts
Great starting points for Face-Swap.
API quick start
Run Face-Swap with a single API call.
{
"prompt": "in a futuristic city plaza at night, surr…",
"inputImage": "https://your-cdn.com/input.png",
"inputImage2": "https://your-cdn.com/input.png",
"inputImage3": "https://your-cdn.com/input.png"
}curl -X POST "https://api.wiro.ai/v1/Run/wiro/face-swap" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_WIRO_API_KEY" \
--data-binary @- <<'JSON'
{
"prompt": "in a futuristic city plaza at night, surr…",
"inputImage": "https://your-cdn.com/input.png",
"inputImage2": "https://your-cdn.com/input.png",
"inputImage3": "https://your-cdn.com/input.png"
}
JSON