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

{
  "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

{
  "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