How to automate photo face swaps in n8n

This guide follows the current Magic Hour API and n8n HTTP Request node. The exact request body can change, so import the current cURL example from the API reference when you build or update the workflow.

Workflow at a glance

• Trigger the workflow and validate that you have permission to process both faces.
• Request signed upload URLs for the local image files.
• PUT each image to its signed URL and retain the returned file_path values.
• POST one Face Swap Photo project with those file paths.
• Store the returned project ID, then poll GET /v1/image-projects/{id}.
• On complete, download downloads[0].url and save the file before the URL expires.
• Route error, canceled, timeout, and invalid-input outcomes to explicit failure handling.

1. Create the credential in n8n

Create a Magic Hour API key in the Developer Hub. In n8n, create an HTTP Header Auth credential with header name Authorization and value Bearer followed by the API key. Select this credential only on requests to api.magichour.ai.

Do not paste a real key into a node, shared workflow JSON, execution log, prompt, or screenshot. If you import cURL from the docs, remove its example Authorization header before selecting the saved n8n credential so the request has one authorization value.

2. Prepare and upload the images

The Face Swap Photo request uses Magic Hour file paths. For local or private files, follow the documented three-step upload flow: request upload URLs, PUT the bytes to those signed URLs, then use each returned file_path in the project request.

• Validate the actual file type and extension before requesting upload URLs.
• Treat upload_url as a short-lived secret and send the file bytes with PUT.
• Do not attach the Magic Hour bearer credential to the signed upload URL.
• Continue only after every upload succeeds and every required file_path is present.

Use a clear, front-facing replacement portrait and a target image with visible faces. Poor lighting, heavy occlusion, tiny faces, extreme angles, or motion blur can reduce quality. Obtain permission from identifiable people and do not use the workflow for impersonation, fraud, harassment, or deceptive content.

3. Submit the face-swap project once

Add an n8n HTTP Request node for POST https://api.magichour.ai/v1/face-swap-photo. The current API requires an assets object and returns an id plus credits_charged. Copy the current body shape from the Face Swap Photo API reference rather than copying an old article screenshot.

Use target_file_path for the image being edited. Configure face_swap_mode and face_mappings exactly as the current reference describes for the faces you intend to replace. If the request fails validation, fix the same request inputs; do not create retries that submit duplicate paid projects after an uncertain network result.

4. Poll the same project ID

Store the id returned by the POST node. After a bounded wait, call GET https://api.magichour.ai/v1/image-projects/{id} with the same n8n credential. Loop that status request with backoff while the project is queued or rendering.

• complete: continue only when downloads contains an item.
• error: stop and preserve the API error for inspection.
• canceled: stop; canceled projects do not emit a cancellation webhook, so polling must detect this state.
• queued or rendering: wait and request the status again without submitting another generation.
• temporary status-request failure: retry the GET within a bounded timeout; retain the project ID for recovery.

The Get Image Details reference is the source of truth for statuses and response fields. Set an overall workflow timeout and a maximum status-request count so an execution cannot loop forever.

5. Download and store the completed image

When status is complete, pass downloads[0].url to a separate HTTP Request node configured to return a file. Do not send your Magic Hour Authorization header to that download URL. Save the binary to durable storage and keep the project ID with the workflow record.

Magic Hour documents 24-hour download URL expiration. If a link expires, call Get Image Details again for a fresh URL; do not pay for another generation. See Handling Inputs and Outputs for the current upload and download contract.

6. Make the automation safe to rerun

• Assign an external workflow record ID before submission and store the Magic Hour project ID immediately after a successful response.
• Before submitting, check whether that record already has a project ID or completed output.
• Separate submit retries from status retries. A failed GET does not imply a failed POST.
• Limit concurrency if a trigger can deliver the same item more than once.
• Record status, credits_charged, error details, output location, and consent or rights evidence without logging the source images unnecessarily.
• Use a review step before any realistic face swap is published or sent externally.

Common failures

• 401 unauthorized: verify the Header Auth credential and the Bearer prefix; remove duplicate Authorization headers.
• 400 or 422 invalid request: compare the body and file paths with the current endpoint schema.
• 404 not found: confirm that the stored project ID is the one returned by the original POST.
• No download: inspect status first; downloads is populated after a successful render.
• Expired URL: fetch the existing project again for a fresh download URL.
• Duplicate charges: inspect whether the submit node ran more than once or whether a status failure was routed back to POST.

Minimal acceptance check

• Run one authorized test image through the complete workflow.
• Confirm there is exactly one POST and one project ID for the test record.
• Observe at least one status branch and confirm only complete reaches download.
• Force or simulate a status-request failure and confirm it retries GET, not POST.
• Confirm the output lands in durable storage and the saved project ID can refresh an expired URL.
• Review the face, hairline, skin edge, lighting, background, hands, text, and other identities at full size before use.

Official sources checked

Request fields and charging behavior come from the Face Swap Photo API reference. Statuses and downloads come from Get Image Details. Upload and URL-expiration behavior come from Handling Inputs and Outputs. n8n credential and HTTP-node behavior comes from the n8n HTTP Request documentation. Sources were checked September 13, 2026.