Character Replace Tool - Magic Hour Docs

​

Overview

​

How It Works

1. Upload a video - Provide the scene containing the person to replace
2. Upload a character image - Provide the replacement character reference
3. Select the subject - Use automatic selection or provide a point and timestamp
4. Choose the segment - Set start time, end time, and output resolution
5. Create and download - Submit the job, poll until complete, then retrieve the output

​

Use Cases

• Character-driven content - Place a recurring character into new footage
• Creative remixes - Recast short clips using a reference image
• Previsualization - Test casting or character concepts before production
• Marketing variants - Adapt one scene with different characters
• Social content - Produce short character transformations for posts

​

Best Practices

• Use a clear reference image - Show the replacement character at useful resolution with good lighting
• Match framing when possible - Similar angles and body visibility help the replacement fit the scene
• Avoid heavy occlusion - Subjects hidden behind objects are harder to track consistently
• Start with automatic selection - Add a point only when the API needs help identifying the subject
• Test short segments - Validate subject tracking before processing a longer clip

​

Code Example

curl --request POST \
  --url https://api.magichour.ai/v1/character-replace \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '
{
  "name": "My Character Replace video",
  "start_seconds": 0,
  "end_seconds": 15,
  "resolution": "720p",
  "assets": {
    "video_file_path": "api-assets/id/1234.mp4",
    "image_file_path": "api-assets/id/5678.png"
  },
  "style": {
    "mode": "replace",
    "selection_mode": "auto",
    "points": [
      {
        "position_x": 320,
        "position_y": 180,
        "time_seconds": 2.5
      }
    ]
  }
}
'

​

Pricing

​

API Reference

​

Related Tools