Video face swap in n8n: reliable Magic Hour API workflow

An n8n video face-swap workflow needs four stages: upload the video and face image, submit one Magic Hour job, poll the returned video-project ID, and download only after status is complete. Store the API key in an n8n credential, keep the project ID across waits, and never resubmit a paid generation because one status check timed out.

• Trigger: manual, form, webhook, schedule or an upstream asset event.

• Upload: request Magic Hour upload URLs, PUT both binary files, and retain both returned file_path values.

• Submit: POST one face-swap video request using the uploaded paths and chosen clip range.

• Poll: GET the same video project after a Wait node until it reaches a terminal state.

• Download: on complete, fetch downloads[0].url as a file without forwarding the Magic Hour API key.

• Store: save the output in durable storage before the temporary download URL expires.

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.

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 by project ID, and retain a recovery poll.

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.