Openjutsu Object Swap API Documentation

Openjutsu Object Swap API Documentation

Playground

Openjutsu Object Swap applies prompt-guided object and scene changes to existing videos, allowing users to replace hair, clothing, objects, or entire backgrounds while preserving the rest of the shot and original audio. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Genjutsu Object Swap (OpenJutsu) changes a selected object, appearance, or background in an existing video while preserving the rest of the scene, camera movement, performance, and original audio.

Name what you want to change, describe the replacement, or provide a reference image to guide the new look.

Why Choose This?

• Targeted video editing — Change specific elements such as hair, clothing, vehicles, or other visible objects.
• Reference-guided replacement — Use an image to guide the appearance of an outfit, hairstyle, product, place, or other element.
• Background replacement — Keep the selected subject while transforming the surrounding environment.
• Original motion preserved — Retain the source video’s movement, timing, and camera behavior.
• Original audio preserved — Keep 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 the target clearly visible.
2. Name the target — Specify what should change.
3. Describe the replacement — Use change_to, or provide a reference image.
4. Choose the mode — Use change for object or appearance replacement, or background for environment changes.
5. Choose resolution — Select 480p, 540p, 768p, or 1080p.
6. Submit — Generate and retrieve the edited video.

Pricing

Pricing is based on the input video duration and selected resolution.

Providing a reference image adds $0.02 per request.

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

• Appearance changes — Change hairstyles, clothing, colors, or accessories.
• Object replacement — Replace products, vehicles, props, and other visible elements.
• Background replacement — Move a subject into a different environment while keeping the person unchanged.
• Product variations — Swap product appearance using text or a reference image.
• Creative video editing — Transform selected parts of existing footage without rebuilding the entire scene.

Pro Tips

• Name the target using a short and specific description.
• Separate multiple targets with commas when several elements should change together.
• Use a reference image when you want a specific visual appearance.
• Keep the source video to one continuous shot for more predictable results.
• Use specific target names to reduce accidental matches.
• Remember that replacement follows the original target’s shape and movement.

Notes

• Input video duration is rounded up to the next whole second for billing.
• video and target are required.
• change_to is required unless a reference image is provided.
• mode defaults to change.
• Multiple targets can be edited in the same request.
• In background mode, the specified target is preserved while the surrounding scene changes.
• Source audio is preserved.
• Mirrors and reflections of the edited target are not supported.
• If no matching target is found, the request may fail.
• 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, appearances, or backgrounds while preserving the source video’s motion and audio.

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

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