# wavespeed-ai/openjutsu/character-swap

> Openjutsu Character Swap replaces people in existing videos with characters from reference images while preserving the original scene, motion, framing, and audio for character replacement, creative video editing, social content, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/wavespeed-ai/openjutsu/character-swap`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `wavespeed-ai/openjutsu/character-swap`
- **Category**: video-to-video

## Pricing

Pricing is based on the input video duration, selected resolution, and number of character images. Billing is per second of input video, and the per-second rate depends on the resolution.

### Price by resolution and video duration (1 character image)

| Resolution | 3 s or shorter (`video.seconds=3`) | 5 s | 10 s | 15 s or longer |
|------------|-----------------:|-----------------:|-----------------:|-----------------:|
| 480p | ~~$0.47~~ $0.235 | ~~$0.77~~ $0.385 | ~~$1.52~~ $0.76 | ~~$2.27~~ $1.135 |
| 540p | ~~$0.53~~ $0.265 | ~~$0.87~~ $0.435 | ~~$1.72~~ $0.86 | ~~$2.57~~ $1.285 |
| 768p (default) | ~~$0.62~~ $0.31 | ~~$1.02~~ $0.51 | ~~$2.02~~ $1.01 | ~~$3.02~~ $1.51 |
| 1080p | ~~$1.22~~ $0.61 | ~~$2.02~~ $1.01 | ~~$4.02~~ $2.01 | ~~$6.02~~ $3.01 |

### Price per extra second of video

Each whole second of video beyond the first `3` seconds adds the following, up to `15` seconds:

| Resolution | Each extra second (4 s minus 3 s) |
|------------|-----------------:|
| 480p | ~~$0.15~~ $0.075 |
| 540p | ~~$0.17~~ $0.085 |
| 768p | ~~$0.20~~ $0.10 |
| 1080p | ~~$0.40~~ $0.20 |

### Character images

Each additional character image adds ~~$0.02~~ $0.01 (2 images minus 1 image).

| Configuration | Price |
|---------------|------:|
| 10 s at 768p, 1 image (`images.count=1`) | ~~$2.02~~ $1.01 |
| 10 s at 768p, 2 images (`images.count=2`) | ~~$2.04~~ $1.02 |
| 10 s at 768p, 3 images (`images.count=3`) | ~~$2.06~~ $1.03 |

Videos shorter than `3` seconds are billed as `3` seconds. Videos longer than `15` seconds use and bill only the first `15` seconds.

---

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`video`** (`string`, _required_):
  URL of the source video. The people in it are replaced by your characters; the scene, motion and original audio are kept. Use a single shot with a person in the first frame. The output follows the video's length, up to 15 seconds.

- **`images`** (`array of string`, _required_):
  URLs of the character pictures, one per person to replace (up to 4). With one picture and no roles, the most prominent person is replaced. With several, or with roles, only the people you describe are replaced and everyone else stays as filmed. A picture nobody in the video matches is left out.

- **`roles`** (`array of string`, _optional_):
  Optional. One short description per picture, in the same order, saying who it replaces, for example "the woman in black on the left". Leave it out and the pictures go to the people in the order they appear in the video, or from left to right when they are on screen together.

- **`resolution`** (`string`, _optional_):
  Output resolution. The price per second rises with it.
  - Default: `"768p"`
  - Options: "480p", "540p", "768p", "1080p"

- **`seed`** (`integer`, _optional_):
  The random seed to use for the generation. A negative value means a random seed will be used.



**Required Parameters Example**:

```json
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ]
}
```

**Full Example**:

```json
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "roles": [],
  "resolution": "768p",
  "seed": 0
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ]
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/wavespeed-ai/openjutsu/character-swap \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/wavespeed-ai/openjutsu/character-swap)
- [API Documentation](https://wavespeed.ai/docs/docs-api/wavespeed-ai/openjutsu-character-swap)
