Overview
This node performs face swapping from an image onto a target video using the PiAPI Video Faceswap API. It supports swapping one or multiple faces with precise control over which faces to swap by specifying their index positions. This is useful for scenarios such as creating personalized videos, entertainment content, or visual effects where you want to replace faces in a video with those from a given image.
Practical examples:
- Replacing a celebrity's face in a video clip with a user's photo.
- Swapping multiple faces in a group video with different images.
- Creating humorous or promotional videos by face swapping.
Properties
| Name | Meaning |
|---|---|
| Multi-Face Support | Notice informing that the node supports swapping multiple faces and that advanced options allow specifying face indices. |
| Swap Image Input Method | Method to provide the swap image: either via URL or binary data. |
| Swap Image Binary Property | (If binary data selected) The name of the binary property containing the swap image data. |
| Swap Image URL | (If URL selected) The URL of the image containing the face(s) to swap. |
| Target Video Input Method | Method to provide the target video: either via URL or binary data. |
| Target Video Binary Property | (If binary data selected) The name of the binary property containing the target video data. |
| Target Video URL | (If URL selected) The URL of the target video that will have faces replaced. Must be MP4 format, max 10MB size, max 720p resolution. |
| Video Requirements | Notice describing video requirements: MP4 format, max 10MB, max 720p resolution, max 600 frames. |
| Enable Multi-Face Selection | Boolean to enable manual selection of specific faces by index. |
| Face Indices Information | (Shown if multi-face selection enabled) Notice explaining how faces are indexed (usually left to right, but can vary). |
| Swap Faces Index | (If multi-face selection enabled) Comma-separated string of indices indicating which faces to use from the swap image (e.g., "0" or "0,1"). |
| Target Faces Index | (If multi-face selection enabled) Comma-separated string of indices indicating which faces to replace in the target video (e.g., "0" or "0,1"). |
| Wait For Completion | Boolean indicating whether to wait for the face swap process to complete before continuing workflow execution. |
| Max Retries | (If waiting for completion) Maximum number of retries to check task status. |
| Retry Interval | (If waiting for completion) Interval between retries in milliseconds. |
Output
The node outputs JSON data containing the status and results of the face swap task:
task_id: Identifier of the submitted face swap task.status: Current status of the task (e.g., "pending", "completed").- If waiting for completion is enabled, the output includes the final task result once completed.
No direct binary output is produced by this node; it returns metadata about the processing task. The actual swapped video must be retrieved separately via the API or subsequent steps.
Dependencies
- Requires an API key credential for the PiAPI service to authenticate requests.
- Uses the PiAPI Video Faceswap API endpoint
/api/v1/taskwith model"Qubico/video-toolkit"and task type"face-swap". - The node expects input images and videos to meet specified format and size requirements.
- No additional external dependencies beyond the configured API credential.
Troubleshooting
- Invalid Image Error: If the error message contains "failed to get valid image", it means the provided swap image could not be processed. Ensure the image is accessible, in JPEG or PNG format, and under 2048x2048 resolution.
- Invalid Video Error: If the error message contains "failed to get valid video", it means the target video is invalid. Confirm the video is MP4 format, under 10MB, maximum 720p resolution, and no more than 600 frames.
- Binary Data Type Mismatch: When providing binary data, ensure the swap image is an image MIME type and the target video is an MP4 video MIME type.
- Task ID Missing: If the API response does not return a valid task ID, the request likely failed; verify all inputs and credentials.
- Use the "Continue On Fail" option to handle errors gracefully without stopping the workflow.
Links and References
- PiAPI Video Faceswap API Documentation (example placeholder link)
- n8n Documentation on Binary Data Handling
- MP4 Video Format Specifications