magic-hour-face-swap
Put a supplied face into an existing video or photo with Magic Hour while preserving the performance, shot and intended cast. Use for face swaps, recasting a clip or putting someone into a scene; use Character Replace when the body, costume or whole character must change.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- magic-hour-face-swap
- license
- MIT
- metadata
- { "author": "magichourhq", "version": "1.1.0" }
- description
- Put a supplied face into an existing video or photo with Magic Hour while preserving the performance, shot and intended cast. Use for face swaps, recasting a clip or putting someone into a scene; use Character Replace when the body, costume or whole character must change.
02 资源文件 2
- 参考文档agents/openai.yaml251 B
- 许可证LICENSE1.1 KB
03 SKILL.md 正文
Magic Hour face swap
Keep the performance the user likes and change the intended face. Accept “put me in this clip”; choose the technical settings and inspect the result within the existing budget. Use supplied authorized media, preserve delegated choices and deliver the actual file.
Choose the right change
Face Swap changes facial identity. It does not promise a new body, hairstyle, costume, scene or voice. Use replace_character_in_video for a whole-character change; use edit_image to establish a new still before Image-to-Video when no source performance exists. Never create a replacement scene from text when the user asked to preserve their clip.
Inspect the source interval, face size, turns, occlusions, motion blur, cuts and other visible people. Use a clear reference of the intended identity with an unobstructed face. Match the reference angle to the difficult portion where possible; a heavily beautified reference can remove distinguishing details. Do not modify protected facial traits to chase generic attractiveness.
For a long or difficult video, render one representative interval containing a turn or obstruction before expanding within budget. A static frontal preview cannot establish reliability through cuts. Keep the original video and audio for comparison and final assembly.
Select the intended face
For one visible person, use swap_face_in_video with assets.video_source: file, assets.video_file_path, assets.image_file_path and assets.face_swap_mode: all-faces. The image is the new identity; the video contains the performance. The live description may mention source_file_path, but the actual schema's input is image_file_path.
For a specific person in a cast, use detect_faces on the exact source asset, then retrieve that detection ID until complete. Inspect the returned face previews to identify the requested person. Use individual-faces with face_mappings: [{original_face: <returned path>, new_face: <reference path>}]. Use the returned path exactly; never invent an index or infer that “left person” is the same person across shots. Do not use all-faces when bystanders must remain unchanged. Ask only when the intended person is genuinely ambiguous.
If cropping or trimming creates a new source asset, run detection against that asset before mapping. start_seconds and end_seconds refer to the submitted video's timeline; a locally trimmed file starts at zero. Preserve output duration and sound intentionally rather than assuming trim offsets behave the same across tools.
For photos, use swap_face_in_photo and then wait_for_image_project. Its fields differ from video: assets.source_file_path supplies the new face and assets.target_file_path is the destination photo for all-faces. For individual-faces, pass the target and inspected face_mappings instead. Do not copy the video tool's image_file_path into this schema. Check the other people as well as the replaced face. A detected crop is a mapping identifier, not a substitute for the user's original identity reference.
The two-person photo example includes both detection previews and a selective replacement. Only the inspected left face was mapped; the other person was visually retained. This validates that photo workflow, not multi-person tracking through video cuts.
Run and inspect
Use the connected creation MCP at https://mcp.magichour.ai/; setup. API users should read the live schema for /v1/face-swap. Choose the version for the observed need; the live schema distinguishes identity handling from skin texture. Check the interval and estimated cost against the existing budget.
Upload local files with get_upload_urls, PUT their raw bytes to the returned URL without the API bearer token, then use file_path. Submit once, save the returned project ID and use wait_for_video_project. Resume the same job after a timeout. Keep signed download URLs intact and save durable output files.
Compare the full result with the original performance and reference: identity on frontal and turned frames; face boundaries at hair, ears and chin; eyes and teeth; occluding hands; unchanged bystanders; cuts; original action and sound. A successful detection or completed job is not a quality pass. When playback is unavailable, identify that limitation.
Probe the downloaded dimensions, frame rate, duration and audio streams. In the published single-person run, a 720 × 1296 source became 568 × 1024. Restore a required canvas only with an appropriate crop or contained layout; stretching or upscaling does not recover lost detail. The original hairstyle remained, illustrating why a face swap is different from changing the whole character.
If identity is weak, change the reference or live-supported version after identifying the failure. If a face switches people, correct mapping or split distinct shots before rendering again. If the requested change includes a costume or silhouette, switch to Character Replace rather than repeat face-only attempts. Repair only the failed interval, inside the authorized budget.
Deliver the finished clip or photo, concise limitations, and the saved source/mapping/project ID for later revisions. Reuse the accepted performance when the next request changes only the cast.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.