Openjutsu Character Swap API Documentation

Openjutsu Character Swap API Documentation

Playground

Genjutsu-style character swap: replace people in a video with characters from your pictures, keeping the scene, motion and original audio.

Features

Genjutsu Character Swap (OpenJutsu) replaces people in a video with characters from your pictures. The scene, camera movement, performance and original audio are kept; only the people you choose change.

Why Choose This?

• One picture, or several Give one picture and the most prominent person is replaced. Give up to four pictures, each with a short description of who it replaces (“the woman in black on the left”), and only those people are replaced; everyone else stays as filmed.

• Performance preserved Body motion, timing and framing follow the source video, so the result stays in sync with the original sound.

• Original audio kept The soundtrack of the source video is carried over to the result.

• Up to 15 seconds The result follows the length of your video, up to 15 seconds. Longer videos use their first 15 seconds.

Parameters

Tips

• Use a source video with one continuous shot and a clearly visible person. Videos without a person are rejected.
• Describe people by how they look or where they are, not by name. A picture nobody in the video matches is left out and the others are still made; if nobody matches any picture, the most prominent person is replaced by the first picture. The video must show a person.
• Use one picture per person in the video you want to replace; people without a picture stay as they are.
• Mirrors and reflections of the person are not supported.
• The result can be slightly shorter than the selected part.

Pricing

> Billing duration: The length of your input video is rounded up to whole seconds. The minimum billed duration is 3 seconds; shorter videos are billed as 3 seconds. Videos longer than 15 seconds are billed as 15 seconds, and only their first 15 seconds are used.

The price depends on the billed length and the resolution. Each character picture adds a flat fee.

A flat 0.02 USD is added for each character picture.

Billing rules

• Billed duration = input video length rounded up to whole seconds, clamped to 3-15 seconds.
• 1080p: 0.40 USD per billed second.
• 768p: 0.20 USD per billed second.
• 540p: 0.17 USD per billed second.
• 480p: 0.15 USD per billed second. Lower resolutions are not proportionally cheaper: finding the people takes the same time at any size.
• Total = billed seconds x rate per second + 0.02 USD x number of pictures.

The number of people replaced does not change the per-second rate. For example, with one picture:

• 10 s video at 768p: 10 x 0.20 + 0.02 = 2.02 USD
• 10 s video at 540p: 10 x 0.17 + 0.02 = 1.72 USD
• 10 s video at 480p: 10 x 0.15 + 0.02 = 1.52 USD
• 10 s video at 1080p: 10 x 0.40 + 0.02 = 4.02 USD
• 15 s video at 768p: 15 x 0.20 + 0.02 = 3.02 USD
• 2 s video at 768p (billed as 3 s): 3 x 0.20 + 0.02 = 0.62 USD
• 30 s video at 768p (billed as 15 s): 3.02 USD
• 10 s video at 768p with two pictures: 10 x 0.20 + 2 x 0.02 = 2.04 USD

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

Response Parameters

Result Request Parameters

Result Response Parameters