Openjutsu Object Swap API Documentation

Openjutsu Object Swap API Documentation

Playground

Genjutsu-style object swap: change hair, clothes or the whole background in a video by naming it, keeping the rest of the shot and the original audio.

Features

Genjutsu Object Swap (OpenJutsu) changes one thing in a video by naming it: hair, a jacket, a car, or the whole background. Only that area is regenerated; the rest of the shot, the camera movement, the performance and the original audio are kept.

Why Choose This?

• Name it, change it Say what to change (hair, jacket, car) and what it becomes (“short bright pink hair”). Everything else in the shot stays as filmed.

• Copy a look from a picture Give a picture of an outfit, a hairstyle, a product or a place and the video takes on its look. The shape and movement of the original are followed.

• New background, same person With background mode the person stays and the setting around them changes: a beach, a studio, a rainy street.

• 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

• Name the target as it looks in the video, in a word or two. Every match changes, so jacket changes every jacket in the shot.
• Several things can be changed together: hair, top.
• change keeps the outline of what it replaces, so a tank top turned into a flannel shirt stays sleeveless. The shape and movement come from the original.
• A picture only needs to show the thing itself: the outfit, the hairstyle, the place.
• Use a video with one continuous shot. Mirrors and reflections of the target are not supported.
• If nothing matching the target is found, the request fails with an error message. If the name is vague it may match something else, so use a specific word.

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. A reference picture adds a flat fee.

A flat 0.02 USD is added when you give a reference picture in image.

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 if image is given.

So, for example:

• 10 s video at 768p: 10 x 0.20 = 2.00 USD
• 10 s video at 540p: 10 x 0.17 = 1.70 USD
• 10 s video at 480p: 10 x 0.15 = 1.50 USD
• 10 s video at 1080p: 10 x 0.40 = 4.00 USD
• 10 s video at 768p with a reference picture: 10 x 0.20 + 0.02 = 2.02 USD
• 15 s video at 768p: 15 x 0.20 = 3.00 USD
• 2 s video at 768p (billed as 3 s): 3 x 0.20 = 0.60 USD
• 30 s video at 768p (billed as 15 s): 3.00 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",
  "target": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "mode": "change",
  "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/object-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