# Face Swap
**Action ID:** `face_swap`
## Description
Perform face swapping between images using PixelML's advanced facial recognition and manipulation technology. This node replaces faces in an image with faces from another image while maintaining natural appearance.
## Provider
**PixelML**
## Connection
| Name | Description | Required | Category |
| ------------------ | ------------------------------------------- | :------: | --------- |
| PixelML Connection | The PixelML connection to call PixelML API. | ✓ | pixel\_ml |
## Input Parameters
| Name | Type | Required | Default | Description |
| ------------------ | ------- | :------: | ------- | ----------------------------------------------------------------------------------------------- |
| source\_image\_url | string | ✓ | - | URL of the source image containing the face to extract. Supported formats: PNG, JPEG, JPG, WEBP |
| input\_image\_url | string | ✓ | - | URL of the input image where the face will be inserted. Supported formats: PNG, JPEG, JPG, WEBP |
| frame\_image\_url | string | ✓ | - | URL of the frame image for positioning. Supported formats: PNG, JPEG, JPG, WEBP |
| frame\_width | integer | ✓ | - | The width of the frame image in pixels |
| frame\_height | integer | ✓ | - | The height of the frame image in pixels |
| image\_width | integer | ✓ | - | The width of the image in pixels |
| image\_height | integer | ✓ | - | The height of the image in pixels |
| image\_x | integer | ✓ | - | The x coordinate of the image in the frame |
| image\_y | integer | ✓ | - | The y coordinate of the image in the frame |
View JSON Schema
```json
{
"description": "face swap node input.",
"properties": {
"source_image_url": {
"description": "URL of the source image containing the face to extract",
"title": "Source image url",
"type": "string",
"json_schema_extra": {}
},
"input_image_url": {
"description": "URL of the input image where the face will be inserted",
"title": "Input image url",
"type": "string",
"json_schema_extra": {}
},
"frame_image_url": {
"description": "URL of the frame image for positioning",
"title": "Frame image url",
"type": "string",
"json_schema_extra": {}
},
"frame_width": {
"description": "The width of the frame image",
"title": "Frame width",
"type": "integer",
"json_schema_extra": {}
},
"frame_height": {
"description": "The height of the frame image",
"title": "Frame height",
"type": "integer",
"json_schema_extra": {}
},
"image_width": {
"description": "The width of the image",
"title": "Image width",
"type": "integer",
"json_schema_extra": {}
},
"image_height": {
"description": "The height of the image",
"title": "Image height",
"type": "integer",
"json_schema_extra": {}
},
"image_x": {
"description": "The x coordinate of the image",
"title": "Image x",
"type": "integer",
"json_schema_extra": {}
},
"image_y": {
"description": "The y coordinate of the image",
"title": "Image y",
"type": "integer",
"json_schema_extra": {}
}
},
"required": [
"source_image_url",
"input_image_url",
"frame_image_url",
"frame_width",
"frame_height",
"image_width",
"image_height",
"image_x",
"image_y"
],
"title": "FaceSwapNodeInput",
"type": "object"
}
```
## Output Parameters
| Name | Type | Description |
| ------ | ----- | ----------------------------------------------------------- |
| images | array | List of URLs of the resulting images with face swap applied |
View JSON Schema
```json
{
"description": "FaceSwap node output.",
"properties": {
"images": {
"title": "Image output",
"type": "array",
"items": {
"type": "string",
"json_schema_extra": {}
}
}
},
"required": [
"images"
],
"title": "FaceSwapNodeOutput",
"type": "object"
}
```
## How It Works
This node performs face swapping by taking a source image (containing the face to extract), an input image (where the face will be placed), and a frame image for proper positioning. The x and y coordinates specify where the input image should be positioned within the frame. The PixelML service detects faces in the source image, extracts them, and seamlessly inserts them into the input image at the specified coordinates, creating a natural-looking result that maintains facial features and expressions.
## Usage Examples
### Example 1: Basic Face Swap
**Input:**
```
source_image_url: "https://images.example.com/person_a.jpg"
input_image_url: "https://images.example.com/body_position.jpg"
frame_image_url: "https://images.example.com/frame.jpg"
frame_width: 800
frame_height: 600
image_width: 400
image_height: 500
image_x: 200
image_y: 50
```
**Output:**
```
images: [
"https://pixelml-output.example.com/faceswap_result_12345.png"
]
```
### Example 2: Face Swap with Precise Positioning
**Input:**
```
source_image_url: "https://storage.example.com/celebrity_face.jpg"
input_image_url: "https://storage.example.com/movie_scene.jpg"
frame_image_url: "https://storage.example.com/scene_frame.jpg"
frame_width: 1920
frame_height: 1080
image_width: 800
image_height: 900
image_x: 560
image_y: 90
```
**Output:**
```
images: [
"https://pixelml-output.example.com/faceswap_cinema_67890.png"
]
```
### Example 3: Multiple Output Variations
**Input:**
```
source_image_url: "https://cdn.example.com/face_source.png"
input_image_url: "https://cdn.example.com/target_body.png"
frame_image_url: "https://cdn.example.com/full_frame.png"
frame_width: 1024
frame_height: 768
image_width: 512
image_height: 600
image_x: 256
image_y: 84
```
**Output:**
```
images: [
"https://pixelml-output.example.com/faceswap_var1_11111.png",
"https://pixelml-output.example.com/faceswap_var2_22222.png"
]
```
## Common Use Cases
* **Entertainment**: Create fun face swap videos and images for social media
* **Movie Production**: Replace faces in film scenes for visual effects
* **Advertising**: Create variations of ads with different faces for targeting
* **Gaming**: Swap player faces into game cutscenes or promotional materials
* **Photo Editing**: Create composites and artistic combinations
* **Training Data**: Generate synthetic face swap data for ML model training
* **Security Testing**: Test facial recognition systems with swapped faces
## Error Handling
| Error Type | Cause | Solution |
| ------------------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Invalid Image URL | One or more image URLs are malformed or inaccessible | Verify all URLs are valid and publicly accessible |
| Unsupported Format | Image format is not PNG, JPEG, JPG, or WEBP | Convert all images to supported formats |
| No Face Detected | Source or input image doesn't contain a detectable face | Use images with clear, visible faces; try different images |
| Face Detection Error | Face detection failed for one or more images | Ensure faces are clearly visible and not obscured |
| Dimension Mismatch | Image dimensions don't match the provided coordinates | Verify frame\_width, frame\_height, image\_width, image\_height, image\_x, image\_y are correct |
| Coordinate Out of Bounds | Image\_x or image\_y place image outside frame bounds | Adjust coordinates to fit within the frame dimensions |
| PixelML Service Error | PixelML API is unavailable | Check your PixelML connection and try again |
| Authentication Error | Invalid or expired PixelML credentials | Verify your PixelML connection configuration |
## Notes
* **Coordinate System**: image\_x and image\_y are measured from the top-left corner of the frame
* **Dimension Validation**: Ensure image\_x + image\_width <= frame\_width and image\_y + image\_height <= frame\_height
* **Face Quality**: Better results with clear, frontal face images without extreme angles or occlusions
* **Multiple Outputs**: The node may return multiple variations for quality assurance
* **Processing Time**: Face swap operations may take longer depending on image size and complexity
* **Natural Blending**: The AI automatically handles blending and color matching for seamless results
* **Supported Formats**: PNG, JPEG, JPG, and WEBP for all input images
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agenticflow.ai/reference/nodes/face_swap.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.