How to swap a full head in an image with Medux MCP
Learn to swap a full head in an image with the Medux API through Codex or Claude MCP. Check inputs, tool calls, task status, and output.
Follow the Codex or Claude workflow
The Medux operation and request fields are shared. Switch tabs for the client-specific prompt, approval pattern, screenshots, and walkthrough.
Codex-specific workflow
Run AI Head Swap as a Codex MCP task
Use the active workspace as the source of truth. Ask Codex to identify the head donor image and target body image, with each role clearly assigned, select the Medux image head-swap tool, and keep the Medux task ID and returned output with the rest of the project. Naming the input roles and the expected result prevents an agent from guessing which file should be used where.
Codex prompt pattern
In this workspace, use the Medux image head-swap tool through Medux MCP to swap a full head in an image.
First inspect and identify the head donor image and target body image, with each role clearly assigned.
Show me the exact tool arguments before execution.
After the task completes, return the head-swapped image and verify that the full intended head region is replaced while the target body and composition remain consistent.Approval gate
Before approving the call, compare the selected tool, file or asset IDs, ordering, timing, and output settings with the request. If a local filename was mapped to an uploaded Medux file ID, keep that mapping visible so it can be audited later.
Result verification
Let Codex monitor an asynchronous task until it reaches a terminal state, then save or report the head-swapped image. The final check is explicit: confirm that the full intended head region is replaced while the target body and composition remain consistent.
Capability boundary: This tutorial targets image head swap: it replaces the broader head region using a donor and target image. Face swap is documented separately because it transfers facial identity while preserving more of the target head.
Before you start
The demo uses two local JPG files. One image provides the replacement head, and the other image provides the base body or scene.
swap_head_src.jpgThe replacement head image. In the video, Codex treats this as the head donor.swap_head_target.jpgThe base image. Medux keeps this image as the body and scene recipient.Step-by-step workflow
Ask Codex to run the Medux head-swap tool
Use a direct prompt. Codex should know which image is the head donor and which image is the target body.
Swap the head in "swap_head_src.jpg" with the head in "swap_head_target.jpg". Use medux. head swap!
Let Codex locate files and select the correct Medux endpoint
Codex lists the local files, finds the Medux head-swap tool, and avoids using a generic face-swap endpoint. This matters because the task is specifically a head replacement, not just a facial blend.
Submit the head-swap task
After both images are uploaded, Codex submits the Medux task. In this demo, swap_head_src.jpg is passed as the replacement head and swap_head_target.jpg is passed as the base image.
Poll until Medux returns the output
Codex keeps checking the task status as it moves from QUEUED to PROCESSING. Once the render is complete, it returns an output file such as head_swap_output.png plus the task ID for traceability.
Source, reference, and generated result
Compare the three images below to see how the source image, target reference, and final Medux output relate to one another.
Publish-ready summary
Medux turns image editing into an agent-friendly workflow. Instead of manually uploading assets, choosing endpoints, and polling job status, Codex can call Medux through MCP and operate the full head-swap pipeline from one prompt.
Use one image as the replacement head and one as the base image.
Codex selects the Medux tool, uploads files, and starts the job.
The final PNG is returned with a task ID for easy checking.
Explore related workflows
Continue with a nearby Medux workflow or compare how the same task works across Claude MCP and Codex MCP.
Claude-specific workflow
Run AI Head Swap as a Claude MCP workflow
Keep the goal, source assets, and constraints together in the conversation. Ask Claude to restate the head donor image and target body image, with each role clearly assigned before proposing the Medux image head-swap tool. That context checkpoint makes the file roles and desired outcome easy to correct before any Medux call is approved.
Claude prompt pattern
Using the assets and requirements in this conversation, help me swap a full head in an image with Medux MCP.
Restate which input fulfills each role: the head donor image and target body image, with each role clearly assigned.
Propose the the Medux image head-swap tool call and summarize its arguments before asking for approval.
When it finishes, return the head-swapped image with a checklist confirming that the full intended head region is replaced while the target body and composition remain consistent.Context checkpoint
Have Claude summarize the intended transformation, identify every source asset by role, and list the important constraints. Review that summary together with the proposed tool arguments; correct the conversation first if a file, order, time range, or setting is ambiguous.
Result verification
Keep the Medux task ID in the conversation while Claude checks progress. When processing ends, ask for the head-swapped image plus a concise validation checklist confirming that the full intended head region is replaced while the target body and composition remain consistent.
Capability boundary: This tutorial targets image head swap: it replaces the broader head region using a donor and target image. Face swap is documented separately because it transfers facial identity while preserving more of the target head.
How the workflow works
Claude handles orchestration. Medux handles image processing. MCP connects the two, keeping the task inside one agent workflow instead of requiring a separate dashboard or custom integration.
Prerequisites
swap_head_src.jpg contains the head or identity to transfer.
swap_head_target.jpg provides the body, pose, clothing, and scene to preserve.
Place both images in a project folder Claude can access.
Enable the Medux connector before starting the task.
Step-by-step guide
Give Claude one precise instruction
Tell Claude which image supplies the new head, which image receives it, and that Medux must be called through MCP. The recording also asks Claude to upload the files with curl.
Swap the head in "swap_head_src.jpg" with the head in
"swap_head_target.jpg". Use Medux through MCP, upload the
files with curl, run the head-swap task, and save the result
in the current project folder.Source, reference, and generated result
Compare the three images below to see how the source image, target reference, and final Medux output relate to one another.
Reusable prompt
Replace the filenames and output path to reuse this workflow.
I have two images in this project:
- [SOURCE_IMAGE] contains the head to transfer.
- [TARGET_IMAGE] contains the body and scene to preserve.
Use the Medux MCP tools to create separate image upload URLs.
Upload both files with curl. Then run the Medux Head Swap task,
wait for completion, and save the final image as [OUTPUT_FILE].
Preserve the target pose, clothing, lighting, and background.Pre-publish checklist
Before using the result on a public page, campaign, or product workflow, review the image carefully and confirm that you have permission to use both source images.
Explore related workflows
Continue with a nearby Medux workflow or compare how the same task works across Claude MCP and Codex MCP.