Pixverse Swap API Documentation

Pixverse Swap API Documentation

Playground

PixVerse Swap replaces backgrounds, people, and objects directly inside existing videos for quick scene changes and creative edits with natural-looking results. Ready-to-use REST inference API, best performance, no cold starts, affordable pricing.

Features

PixVerse Swap generates high-quality video clips by swapping the person, objects, or background of a source video using a reference image. It preserves the original motion, timing, and camera work while replacing the visual target with the new look from the image.

What it does

• Takes a source video (performance, camera motion, timing).
• Takes a reference image (new person, object, or background).
• Replaces the selected target in the video with the content from the image.
• Keeps motion, expressions, and framing consistent so the edit feels natural.

Ideal for:

• Turning talking-head videos into stylized or character performances
• Swapping outfits, props, or featured products
• Dropping your subject into new scenes without reshooting

Inputs and Controls

• video (required) Source clip whose motion, expressions, and timing you want to keep.

• image (required) Reference image that defines the new person, object, or background.

• resolution

• 360p

• 540p

• 720p

• mode

• person – Replace the main person in the video with the person or character from the image.

• object – Replace a key object (for example, smartphone, product, prop) with the object in the image.

• background – Keep the subject but replace the scene behind them using the reference image.

Pricing

• P.S: $0.020 per request for mask selection (charged once per job).

How to Use

1. Upload or paste the URL of your source video.
2. Upload or paste the URL of the reference image that contains the new person, object, or background.
3. Choose the resolution (360p, 540p, or 720p) according to your quality and cost needs.
4. Select the mode:

• person for full character swap,
• object for prop/product replacement,
• background to move your subject into a different environment.

5. Click Run and wait for the processed video to appear in the preview panel.
6. Review the result and download if you are satisfied.

Notes

• An uploaded video in supported formats (mp4, mov)
• Max resolution: 1920
• Max file size: 50MB
• Max duration: 30 seconds

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'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "resolution": "720p",
  "mode": "person"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/pixverse/swap" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL=$(printf '%s' "${TASK}" | jq -r '.urls.get // empty')
if [ -z "${RESULT_URL}" ]; then RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"; fi

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    created|processing) sleep 2 ;;
    *) printf 'Unexpected status: %s
' "${STATUS}" >&2; exit 1 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters