Openjutsu Character Swap API Documentation

Openjutsu Character Swap API Documentation

Playground

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.

Features

Genjutsu Character Swap (OpenJutsu) replaces people in an existing video with characters from reference images while preserving the original scene, camera movement, performance, and audio.

Use one image to replace the most prominent person, or provide multiple images with role descriptions to control which people should be replaced.

Why Choose This?

• Character replacement — Replace people in an existing video with characters from reference images.
• Up to 4 character images — Replace multiple people in the same scene.
• Role-based matching — Describe who each reference image should replace.
• Performance preserved — Keep the source video’s body motion, timing, framing, and camera movement.
• Original audio preserved — Retain the source soundtrack in the final result.
• Up to 1080p output — Choose 480p, 540p, 768p, or 1080p.

Parameters

How to Use

1. Upload a source video — Use a continuous shot with at least one clearly visible person.
2. Add character images — Provide one image for each person you want to replace.
3. Add roles optional — Describe which person each image should replace when multiple people appear.
4. Choose resolution — Select 480p, 540p, 768p, or 1080p.
5. Set a seed optional — Use a fixed seed when comparing variations.
6. Submit — Generate and retrieve the character-swapped video.

Pricing

Pricing is based on the input video duration, selected resolution, and number of character images.

Each character image adds $0.02.

Example Costs

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

Best Use Cases

• Character replacement — Replace actors or people while preserving the original performance.
• Creative remixes — Recast existing footage with new characters.
• Marketing content — Adapt existing video performances with different character appearances.
• Storytelling — Reuse motion and cinematography while changing who appears in the scene.
• Multi-character scenes — Replace selected people while leaving others unchanged.

Pro Tips

• Use a continuous source shot with clearly visible people.
• Use one reference image per person you want to replace.
• Describe people by appearance or position rather than by name.
• Use roles when several people appear in the same scene.
• Use clear character images with visible facial and clothing details.
• Avoid source footage where mirrors or reflections are important.

Notes

• Input video duration is rounded up to the next whole second for billing.
• The person to replace must be visible in the first frame.
• Each roles entry supports up to 200 characters. The number of entries must not exceed the number of input images.
• Up to 4 character images are supported.
• With one image and no roles, the most prominent person is replaced.
• With multiple images and no roles, images are matched to people by appearance order or left-to-right position.
• Source audio is preserved.
• Videos longer than 15 seconds use only the first 15 seconds.

Related Models

• OpenJutsu Character Swap — Replace people in existing videos using character reference images.
• OpenJutsu Object Swap — Replace objects in existing videos while preserving the original scene and motion.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

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"
  ],
  "resolution": "768p"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/openjutsu/character-swap" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters