How to replace a character in a video with Medux MCP
Learn to replace a character in a video 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 Video Character Replacement as a Codex MCP task
Use the active workspace as the source of truth. Ask Codex to identify the source video, reference character image, and replacement instructions, select medux_video_character_replacement, 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_video_character_replacement through Medux MCP to replace a character in a video.
First inspect and identify the source video, reference character image, and replacement instructions.
Show me the exact tool arguments before execution.
After the task completes, return the character-replaced MP4 and verify that the intended character is replaced consistently and the video plays from start to finish.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 character-replaced MP4. The final check is explicit: confirm that the intended character is replaced consistently and the video plays from start to finish.
Before you start
The video uses a simple two-asset setup. Keep the filenames easy to reference so Codex can plan the flow without extra clarification.
Use a video that contains the person you want to replace. In the demo, the file is named character.mp4.
Use a clear character image as the replacement target. In the demo, the file is named character.jpg.
project/
├── character.mp4 # source video with the original person
└── character.jpg # reference character image for replacementWorkflow overview
The whole task can be summarized as five steps.
Give Codex a focused instruction
Tell Codex exactly which video to process, which image to use as the character reference, and how the files should be uploaded. This avoids a vague creative prompt and turns the task into an executable media workflow.
Perform a video character replacement by replacing the person in character.mp4 with the character from character.jpg. Upload the files using curl commands.
Let Codex inspect the workspace and choose the Medux path
Codex checks the project files, looks for existing upload or replacement scripts, and confirms the Medux API flow. In the demo, Codex finds a direct path: generate fresh upload URLs, upload both local files, submit the character replacement task, and poll it to completion.
Approve the Medux MCP upload and replacement calls
Codex asks for permission before it runs Medux tools. First it creates upload URLs for the video and image. Then it uploads the assets with curl. After both uploads return successfully, Codex submits the replacement job.
# Example upload shape. The real URL is generated by Medux.
curl -X PUT "<MEDUX_PRESIGNED_UPLOAD_URL>" -H "Content-Type: video/mp4" --upload-file "character.mp4"
curl -X PUT "<MEDUX_PRESIGNED_UPLOAD_URL>" -H "Content-Type: image/jpeg" --upload-file "character.jpg"For the replacement request, Codex passes the uploaded file IDs into the Medux video character replacement tool.
medux_video_character_replacement(
source_video_file_id="<uploaded_video_file_id>",
target_character_image_file_id="<uploaded_image_file_id>",
title="character.mp4 character replacement"
)
Poll the Medux task until the render is ready
Video generation takes longer than a quick image edit, so Codex keeps checking the same task instead of restarting it. The status moves from QUEUED to PROCESSING, then finishes when Medux returns the output URL.
# Status flow shown in the tutorial
QUEUED → PROCESSING → SUCCEEDED
Download and verify the final video
When the task succeeds, Medux returns the final MP4 URL. Codex downloads the result into the workspace and verifies the output. In the demo, the finished file is saved as character_replacement_result.mp4.
# Example result step
curl -L "<MEDUX_RESULT_VIDEO_URL>" -o "character_replacement_result.mp4"
# Optional local check
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 "character_replacement_result.mp4"
Why this workflow is useful
Medux handles the AI rendering, while Codex handles the operating work: checking assets, creating upload targets, running the correct MCP tool, tracking the job, and saving the final video. The result is a repeatable video character replacement workflow without a separate upload dashboard or custom API script.
Example result
src / tgt / rst demonstration
Below is the complete character-replacement example: src is the original source video, tgt is the reference character, and rst is the final video generated by Medux.
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 Video Character Replacement as a Claude MCP workflow
Keep the goal, source assets, and constraints together in the conversation. Ask Claude to restate the source video, reference character image, and replacement instructions before proposing medux_video_character_replacement. 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 replace a character in a video with Medux MCP.
Restate which input fulfills each role: the source video, reference character image, and replacement instructions.
Propose the medux_video_character_replacement call and summarize its arguments before asking for approval.
When it finishes, return the character-replaced MP4 with a checklist confirming that the intended character is replaced consistently and the video plays from start to finish.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 character-replaced MP4 plus a concise validation checklist confirming that the intended character is replaced consistently and the video plays from start to finish.
Workflow at a glance
Claude handles the orchestration. Medux handles the AI video processing.
Prerequisites
character.mp4 and a reference character image such as character.jpg.Example project folder/Users/your-name/projects/medux-character-replacement/
├── character.mp4
└── character.jpgStep-by-step guide
Give Claude one clear instruction
Describe the target video, the reference image, and the desired outcome in one request. Claude can then plan the workflow and choose the correct Medux tools.
PromptPerform a video character replacement by replacing the person in
character.mp4 with the character from character.jpg.
Upload the files using curl commands.
Create upload URLs and send both files
Claude calls medux_file_create_upload_url for the MP4 and JPG, then uploads them to the returned signed URLs. In the recorded workflow, Claude uses curl because direct uploads are restricted by the sandbox network.
Upload patterncurl -X PUT -H "Content-Type: video/mp4" --data-binary @"/path/to/character.mp4" "SIGNED_UPLOAD_URL_FOR_VIDEO"
curl -X PUT -H "Content-Type: image/jpeg" --data-binary @"/path/to/character.jpg" "SIGNED_UPLOAD_URL_FOR_IMAGE"Long paths and signed URLs wrap inside the code block, so the command stays within the page width on desktop and mobile.
Start the Medux character-replacement job
After both uploads succeed, Claude passes the uploaded file references to medux_video_character_replacement. Medux then analyzes the source clip, follows the original motion, and renders the new character into the scene.
Let Claude monitor the render
The Medux task may remain queued or processing for several minutes. Claude uses medux_task_query to check the status repeatedly, so you do not need to manually refresh another dashboard.
Status logicQUEUED → PROCESSING → COMPLETED
If the task is still processing:
wait briefly, then call medux_task_query again.
Open the completed video
When the task reaches COMPLETED, Claude returns the output link. Open it to review the replacement, confirm that motion and scene continuity are preserved, and save the final file.
Result returned by Medux
Example result
src / tgt / rst demonstration
Below is the complete character-replacement example: src is the original source video, tgt is the reference character, and rst is the final video generated by Medux.
Why use Medux through MCP?
The workflow stays inside Claude: one prompt, automatic file preparation, tool selection, task submission, status checks, and result retrieval. You avoid building a separate upload interface or writing a custom API client for every video operation.
Quick recap
character.mp4 + character.jpg
↓
Claude locates the files
↓
Medux creates signed upload URLs
↓
curl uploads both assets
↓
medux_video_character_replacement
↓
medux_task_query until COMPLETED
↓
Download the replaced-character videoExplore related workflows
Continue with a nearby Medux workflow or compare how the same task works across Claude MCP and Codex MCP.