Video face swap in n8n: reliable Magic Hour API workflow

You want n8n to run video face swaps without losing track of uploads or repeating a paid request. The risky moment is often a timeout during a status check, when the original generation may still be running.

This guide separates the video and face-image uploads from submission, polling and download. You’ll see how to retain the file paths and project ID across waits, keep the API credential protected and store the completed result before its signed URL expires. Start with one representative clip, then make recovery operate on the existing job rather than returning automatically to the create step.

1. Create the Magic Hour credential in n8n

Magic Hour’s API quickstart uses bearer authentication. In n8n, create one HTTP Header Auth credential with header name Authorization and value Bearer followed by the API key. Select that credential on Magic Hour API nodes rather than pasting a real key into workflow JSON.

n8n’s HTTP Request documentation explains credentials, cURL import and file responses. When importing an example cURL command, remove its placeholder Authorization header and select the saved credential so the request sends only one authorization value.

2. Upload the video and replacement face

Magic Hour’s input and output guide documents a three-step upload: request temporary upload URLs, PUT the bytes to those URLs, then use each returned file_path in the generation request. A path on the n8n host is not automatically readable by Magic Hour.

• Request two upload items. Use type video with the actual extension and type image with the actual extension.

• PUT each binary file. Send the bytes to its matching upload_url; do not attach the Magic Hour bearer credential to the signed storage URL.

• Persist both paths. Keep the returned video file_path and image file_path through the rest of the workflow. Requesting URLs alone does not upload anything.

3. Submit one Face Swap video job

Open the current Face Swap Video API reference and import its cURL request into an n8n HTTP Request node. Use POST https://api.magichour.ai/v1/face-swap, JSON content type and the saved Magic Hour credential.

For a file-based job, set video_source to file, pass the uploaded video_file_path and image_file_path, choose start_seconds and end_seconds, and use the documented face_swap_mode and mapping fields for the workflow you intend. Do not send both placeholder and real input modes.

The response contains an id and an estimated credits_charged value. Save the id in your own workflow record immediately; it is the only identifier the polling loop should use.

4. Poll the video project without duplicating work

After the submit node, add a Wait node and then call Get Video Details with GET https://api.magichour.ai/v1/video-projects/{id}. Insert the saved submit response ID into the path and use the same Magic Hour credential.

Route the documented states explicitly:

• draft: project exists but is not rendering; inspect the submission path.

• queued: wait, then poll the same ID.

• rendering: wait, then poll the same ID.

• complete: continue only when downloads contains an item.

• error: stop, record the error object and apply the product’s failure handling.

• canceled: stop; do not submit another request automatically.

Use a bounded interval and an overall workflow timeout. A temporary 429, 500 or network failure on the GET node should retry the status request with backoff; it should never loop back to POST /v1/face-swap.

5. Download and store the result

When status is complete, pass downloads[0].url to a separate HTTP Request node configured to return a file. Do not select the Magic Hour credential on that signed download request.

Save the binary output to your own object storage or destination system. Keep the project ID and expires_at beside it. If the URL expires before download, fetch the same project details again instead of regenerating the video.

See the video face-swap operation

Magic Hour’s recorded video face-swap tutorial shows a clip paired with a replacement portrait. It illustrates the visual operation completed by the API job. Follow the n8n upload, project-ID and polling instructions above for automation; this recording demonstrates the browser workflow. Watch the source video

Polling or webhooks?

Polling is easier to understand in a first n8n workflow and is required to detect canceled projects because canceled does not emit a webhook. For higher volume, use Magic Hour webhooks for started, completed and errored events, verify the delivery as documented, deduplicate each business effect using an application-owned key such as account, project ID and notification kind, and retain a recovery poll. A project-ID-only key can suppress completion after a started event for the same project. Use the secure webhook receiver guide for raw-body verification, durable acceptance and recovery without another paid generation.

Production checks

• Consent and rights: both the target footage and replacement face are authorized for the intended use.

• Input validation: extension, size, duration and clip range meet the current endpoint contract.

• Idempotency: one internal job owns one provider project ID; retries never repeat submission blindly.

• Cost: show or log the estimate and reconcile the final credits_charged value after completion.

• Privacy: define retention for inputs, outputs, n8n execution data and downstream storage.

• Observability: record internal job ID, Magic Hour ID, state transitions, elapsed time and terminal error.