Learn to swap faces in an image with the Medux API through Codex or Claude MCP. Check inputs, tool calls, task status, and output.
Watch the complete workflow: swap faces in an image with Codex, Claude, MCP, and Medux.Watch on YouTube ↗
Choose your AI client
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 Image Face Swap as a Codex MCP task
Use the active workspace as the source of truth. Ask Codex to identify the source face image and target image, with each role clearly assigned, select medux_image_face_swap, 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 medux_image_face_swap through Medux MCP to swap faces in an image.
First inspect and identify the source face image and target image, with each role clearly assigned.
Show me the exact tool arguments before execution.
After the task completes, return the face-swapped image and verify that the intended face is transferred while the target pose, lighting, and broader head 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 face-swapped image. The final check is explicit: confirm that the intended face is transferred while the target pose, lighting, and broader head remain consistent.
Capability boundary: This tutorial targets image face swap: it transfers facial identity while preserving more of the target head, pose, and lighting. It is a separate capability from head swap, which replaces the broader head region.
What this tutorial does
Medux operation
Swap a face from one image onto another while keeping the target pose and lighting.
Agent workflow
Codex selects medux_image_face_swap, presents the arguments for review, calls Medux, and reports the response.
Before you start
Authentication
Authentication is required via Authorization header.
Preconditions
Upload the source file and create a file reference before calling this endpoint.
Successful requests return a Medux task record immediately. Use the task query or sync endpoints to track completion.
All file inputs must be uploaded and persisted as file references before submission.
Prompt Codex
Start with a clear instruction that names the Medux operation and the intended inputs.
Swap a face from one image onto another while keeping the target pose and lighting.
Request fields to review
Confirm these values before approving the MCP tool call. The linked API page remains the source of truth for current limits and response semantics.
Field
Type
Requirement
Purpose
source_image_file_id
string
Required
Source image file id.
target_face_image_file_id
string
Required
Target face image file id.
model_id
string
Optional
Face swap model id. Default: image-face-swap-default.
title
string
Optional
Optional task title.
Step-by-step workflow
01
Connect Medux MCP to Codex
Add the Medux remote MCP endpoint to Codex, provide an authorized credential, and confirm that the medux_image_face_swap tool is available.
02
Prepare the required inputs
Prepare the source files, asset IDs, text, or settings required by the operation. Upload local media first when the tool requests file IDs.
03
Ask Codex to run Image Face Swap
Use one direct instruction with the intended values. Codex should select the Medux tool and show the proposed arguments before execution.
04
Review and approve the tool call
Check that the tool is medux_image_face_swap and that each file ID, task ID, option, and output setting matches your request before approving it.
05
Check the Medux response
If Medux returns an asynchronous task, let the agent monitor it until completion; otherwise review the immediate response and save any result identifiers or output URLs.
Workflow recap
User goal
↓
Codex selects medux_image_face_swap
↓
Review inputs and approve the tool call
↓
Medux runs Image Face Swap
↓
Codex reports the response and output
Frequently asked questions
Can Codex use the Medux Image Face Swap API through MCP?
Codex can call the medux_image_face_swap Medux MCP tool to swap a face from one image onto another while keeping the target pose and lighting. This guide covers the required inputs, approval flow, result handling, and the matching API reference.
Which MCP tool does this tutorial use?
This workflow uses medux_image_face_swap. Review its arguments before approval and consult the API reference for the current contract.
Claude-specific workflow
Run AI Image Face Swap as a Claude MCP workflow
Keep the goal, source assets, and constraints together in the conversation. Ask Claude to restate the source face image and target image, with each role clearly assigned before proposing the Medux image face-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 faces in an image with Medux MCP.
Restate which input fulfills each role: the source face image and target image, with each role clearly assigned.
Propose the the Medux image face-swap tool call and summarize its arguments before asking for approval.
When it finishes, return the face-swapped image with a checklist confirming that the intended face is transferred while the target pose, lighting, and broader head 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 face-swapped image plus a concise validation checklist confirming that the intended face is transferred while the target pose, lighting, and broader head remain consistent.
Capability boundary: This tutorial targets image face swap: it transfers facial identity while preserving more of the target head, pose, and lighting. It is a separate capability from head swap, which replaces the broader head region.
Workflow overview
Claude acts as the operator, MCP provides the connection, and Medux performs the image processing. You only need a source image, a target-face image, and a clear instruction.
Choose source image
Choose target face
Upload both files
Run Medux task
Download result
Before you start
Source imageThe main photo whose face will be replaced.
swap_face_src.jpg
Target-face imageThe image containing the face you want to transfer.
swap_face_target.jpg
Best practice: use clear, front-facing images with visible facial features and similar viewing angles for a cleaner result.
Step-by-step
1
Give Claude one clear instruction
Tell Claude exactly which file is the source, which file provides the replacement face, and that Medux should be called through MCP.
Swap the face in "swap_face_src.jpg" with the face in "swap_face_target.jpg".
Use Medux through MCP. Upload the files with curl, run the face swap, and save the result locally.
A concise prompt gives Claude the complete goal and the two input filenames.
2
Let Claude request upload URLs
Claude calls the Medux integration to create upload locations for both images. This keeps the transfer step inside the same workflow.
Claude obtains separate upload URLs and prepares both image uploads.
3
Upload both files with curl
The recording uses a short shell script to upload the source and target images. Keep paths quoted so filenames with spaces are handled safely.
curl -X PUT "$SOURCE_UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @"/path/to/swap_face_src.jpg"
curl -X PUT "$TARGET_UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @"/path/to/swap_face_target.jpg"
4
Run the Medux face-swap task
After both files are available, Claude submits the face-swap job to Medux and polls the task until processing is complete.
Claude handles the task orchestration. Medux performs the actual face replacement while preserving the rest of the source image.
The Medux job is running and Claude continues checking its status.
5
Open or download the result
When the task finishes, Claude returns a direct result URL and a ready-to-run command for saving the generated image locally.
The final response includes the result link, a local download command, and confirmation that the source face was replaced.
Example result
See the face-swap result
The three images below show the complete workflow: src is the original source image, tgt is the reference target image, and rst is the final generated result.
Source image
src — Original source image used for the face swap.Target reference
tgt — Reference target image that provides the body, pose, clothing, and scene.Generated result
rst — Final face-swap image generated through Medux.
Why this workflow is useful
You do not need to build a custom API client or move between multiple dashboards. Claude understands the request, MCP exposes the Medux tools, and Medux handles the image transformation.
One natural-language request
Automated uploads and task polling
Direct result URL and local file
Quick checklist
Before runningConfirm both images exist, filenames are correct, and the Medux MCP connection is available.
After runningPreview the output and check face alignment, lighting consistency, and natural blending.
Explore related workflows
Continue with a nearby Medux workflow or compare how the same task works across Claude MCP and Codex MCP.
Connect either Codex or Claude to Medux MCP, prepare the required inputs, review the proposed medux_image_face_swap call, and verify the returned result. The tabs above keep client-specific prompting on one canonical page.
Can I use the same Medux tool in Codex and Claude?
Yes. The client interaction differs, but both use the same Medux MCP tool and API request contract shown in this tutorial.
Related developer intent
Use AI agents to swap faces in an image
This tutorial addresses developer workflows for AI face swap API and swap faces in a photo with AI by making the task repeatable through the Medux API. Codex or Claude can prepare inputs, show the MCP tool arguments for approval, monitor processing, and return an output that can be checked against the original request.
This capability can feed an image-to-video AI pipeline by preparing the source image, preserving the intended subject, and passing an approved asset into a photo-to-video or AI image-animation workflow.
Can Codex or Claude swap faces in an image through Medux MCP?
Yes. Use the client-specific tab above to prepare the inputs, review the Medux tool call, run the operation, and verify the returned result. The linked API reference remains the source of truth for supported fields and limits.
Production, trust, and developer intent
Add consent and review controls when you swap faces in an image
Treat this as a consent-based, auditable workflow for swap faces in an image. Use only a voice, face, avatar, or reference asset that you own or have explicit permission to process; keep the source authorization, approved prompt, Medux task ID, and accepted output together for later review.
For production use, pair the Medux API with your own consent records, identity checks, access controls, retention rules, and human approval. These tutorials promote responsible AI media use but do not claim automatic consent verification.
What makes an AI avatar or voice workflow consent-based?
Document who authorized the source material, restrict who can submit tasks, keep the approved inputs and output together, and require review before publishing or reusing a likeness or voice.
