HomeCommunityDiscordLogin

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

PreviousFace DetailerNextRun FAL Model

Last updated

Was this helpful?