Name: Video Character Replacement API (Wan 2.2 Animate)
Brand: magicapi
SKU: api-magicapi-video-character-replacement-api-wan-video-wan-2-2-animate-replace
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Video Character Replacement API (Wan 2.2 Animate)

## Overview
The Video Character Replacement API runs Wan 2.2 Animate, a model from Wan (Alibaba), to replace a character in a video scene. You send a video and an image of a new character, and the model returns a video in which the character from your image takes the place of the character in the original scene.

You can process at 480 or 720 resolution, keep or drop the input video's audio, and turn on extra speed optimizations.

## Features
- Replaces the character in an input video with the character from an input image.
- Two processing resolutions: `480` and `720` (default).
- Optionally merges the audio from the input video into the output (`merge_audio`, on by default).
- Optional `go_fast` mode that applies additional optimizations for faster generation.
- Optional `seed` (leave blank for a random seed).
- Pay As You Go pricing per second of output video.

## Use Cases
1. **Alternate versions of a clip**  
   Make several versions of the same footage, each with a different character, from one source video.

2. **Advertising variants**  
   Swap the person in an ad video to produce versions for different audiences.

3. **Character previews**  
   Place a game, mascot or illustrated character into real footage to see how it looks in motion.

4. **Social media content**  
   Put your own character into an existing video clip.

## Visual Examples
This is a real request sent through api.market.

**Input video** (a woman in a yellow raincoat on a rainy street at night): [Watch the input video](https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4)

**Character image:**

![Character image: a 3D-rendered astronaut figure on a plain grey background](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

**Settings:** `resolution: "480"`, `merge_audio: false` (the input video has no audio track). All other fields used their defaults.

**Output video** (the astronaut takes the place of the woman in the same street scene): [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/wan-2.2-animate-replace-output-api-market.mp4)

## Pricing
- Price: $0.025 per API unit.
- 1 API unit = 1 second of output video at the base rate. The total for a request is rounded up to a whole unit.
- `resolution: "480"`: 1 unit per second, which is $0.025 per second.
- `resolution: "720"` (the default, also used when you do not set `resolution`): 2.5 units per second, which is $0.0625 per second.
- Worked example: a 10 second output video costs 10 units ($0.25) at 480, or 25 units ($0.625) at 720. A 5 second output at 720 is 12.5 units, rounded up to 13 units ($0.325).
- `go_fast`, `merge_audio` and `seed` do not change the price.
- Failed or canceled predictions are not billed.
- GET requests to check prediction status are free and don't count toward API unit usage.
- No monthly subscription fee. Pay As You Go (PAYG): you only pay for what you use.

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API is asynchronous:
1. POST `/predictions` with a `version` and an `input` object. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` (for example once per second) while the status is `starting` or `processing`.
3. Stop when the status is `succeeded` (the `output` field holds the video URL), `failed` or `canceled` (the `error` field explains why).

Video jobs can take several minutes, so allow a generous client timeout (the examples below use 10 minutes).

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
  "version": "33ec6b986ba9010eee4cd812be67d25e72150fad7d2b11d3abed66a9c7ac1ba1",
  "input": {
    "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
    "character_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
    "resolution": "480",
    "merge_audio": false
  }
}'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "33ec6b986ba9010eee4cd812be67d25e72150fad7d2b11d3abed66a9c7ac1ba1",
  "status": "starting",
  "created_at": "2026-10-13T10:37:01.920Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/wan-2.2-animate-replace-output-api-market.mp4",
  "created_at": "2026-10-13T10:37:01.920Z",
  "started_at": "2026-10-13T10:37:03.112Z",
  "completed_at": "2026-10-13T10:39:12.480Z"
}
```

### Status Codes
- 200 OK: prediction status returned.
- 201 Created: prediction created; poll it for the result. This is a success response.
- 400 Bad Request: invalid or missing input fields.
- 401 Unauthorized: missing or invalid API key.
- 404 Not Found: no prediction with that id.
- 429 Too Many Requests: rate limit exceeded; wait and retry.
- 500 Internal Server Error or 503 Service Unavailable: temporary server problem; retry with backoff.

### Error Handling
- Treat both 200 and 201 as success on the create call.
- A prediction can be accepted (201) and still end with `status: "failed"`. Read the `error` field in that case; failed predictions are not billed.
- Retry 429 and 5xx responses with exponential backoff. Do not retry 400 or 401 without fixing the request or key.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide

### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace";

async function runPrediction(input) {
  const create = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-market-key": apiKey },
    body: JSON.stringify({ version: "33ec6b986ba9010eee4cd812be67d25e72150fad7d2b11d3abed66a9c7ac1ba1", input })
  });
  if (create.status !== 200 && create.status !== 201) {
    throw new Error(`API error: ${create.status} ${await create.text()}`);
  }
  const { id } = await create.json();

  const deadline = Date.now() + 600000; // 10 minutes
  while (Date.now() < deadline) {
    const res = await fetch(`${baseUrl}/predictions/${id}`, { headers: { "x-api-market-key": apiKey } });
    if (!res.ok) throw new Error(`API error: ${res.status} ${await res.text()}`);
    const prediction = await res.json();
    if (prediction.status === "succeeded") return prediction.output;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "unknown error"}`);
    }
    await new Promise((r) => setTimeout(r, 1000));
  }
  throw new Error("Prediction timed out after 10 minutes");
}

runPrediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "character_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
  "resolution": "480",
  "merge_audio": false
}).then((output) => console.log(output));
```

### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace"

def run_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    create = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "33ec6b986ba9010eee4cd812be67d25e72150fad7d2b11d3abed66a9c7ac1ba1", "input": input_data},
    )
    if create.status_code not in (200, 201):
        raise Exception(f"API error: {create.status_code} {create.text}")
    prediction_id = create.json()["id"]

    deadline = time.time() + 600  # 10 minutes
    while time.time() < deadline:
        res = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers={"x-api-market-key": API_KEY})
        if res.status_code != 200:
            raise Exception(f"API error: {res.status_code} {res.text}")
        prediction = res.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'unknown error'}")
        time.sleep(1)
    raise Exception("Prediction timed out after 10 minutes")

print(run_prediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
  "character_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
  "resolution": "480",
  "merge_audio": False
}))
```

### cURL
```bash
# Step 1: create the prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
  "version": "33ec6b986ba9010eee4cd812be67d25e72150fad7d2b11d3abed66a9c7ac1ba1",
  "input": {
    "video": "https://blog.api.market/wp-content/uploads/2026/10/hailuo-2.3-fast-output-api-market.mp4",
    "character_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
    "resolution": "480",
    "merge_audio": false
  }
}'

# Step 2: poll until status is succeeded, failed or canceled (replace PREDICTION_ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/video-character-replacement-api-wan-video-wan-2-2-animate-replace/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## Input Parameters
| Parameter | Type | Required | Default | Allowed values | Description |
|-----------|------|----------|---------|----------------|-------------|
| `video` | string (URL) | Yes | none | - | Input video containing the character to be replaced. |
| `character_image` | string (URL) | Yes | none | - | New character image to replace the original character. |
| `resolution` | string | No | `"720"` | `"720"`, `"480"` | Resolution for processing. |
| `go_fast` | boolean | No | `false` | - | Apply additional optimizations for faster generation. |
| `seed` | integer | No | none | - | Random seed. Leave blank for random. |
| `merge_audio` | boolean | No | `true` | - | Merge audio from input video into output. |
| `refert_num` | integer | No | `1` | `1`, `5` | Number of reference frames to use (1 or 5). Deprecated, will always be set to 1. |
| `frames_per_second` | integer | No | `30` | 5 to 60 | Frames per second for output video. Deprecated, will always be set to 30. |

`frames_per_second` and `refert_num` are deprecated: the model always uses 30 frames per second and 1 reference frame, whatever you send.

## Output
A single URL (string) pointing to the generated MP4 video.

## FAQ
1. **Which inputs are required?**  
   `video` (the clip with the character to replace) and `character_image` (the new character). Both are URLs.

2. **What happens to the audio of my video?**  
   With `merge_audio: true` (the default) the audio from the input video is merged into the output. Set it to `false` for a silent output, or when the input video has no audio, as in the example above.

3. **How long does a job take?**  
   It depends on the length of the video, the resolution and `go_fast`. Poll the status endpoint until the prediction finishes.

4. **How is the price calculated?**  
   By the length of the output video in seconds, times 1 unit per second at 480 or 2.5 units per second at 720, rounded up to a whole unit, at $0.025 per unit.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Replace the character in a video scene with a character from an image using Wan 2.2 Animate. Pay per second of output video.