Pruna AI P Video 2 Pro Replace API Documentation

Pruna AI P Video 2 Pro Replace API Documentation

Playground

Pruna AI P-Video-2-Pro Replace swaps the person in a video for the person in one or two reference photos while keeping the motion, camera and soundtrack, with lips following the original audio. Supports 1 to 120 second videos and up to 4K output. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Pruna AI P-Video-2 Pro Replace replaces one or two people in an existing video using reference photos while preserving the source motion, camera movement, timing, and soundtrack. Lip movements follow the original audio unless ignore_audio is enabled.

Why Choose This?

• Character replacement — Replace one or two people in an existing video using reference photos.
• Performance preserved — Keep the source motion, camera movement, timing, and framing.
• Audio-aware lip movement — Lip movements follow the source audio by default.
• Original soundtrack preserved — Keep the source audio in the final video with save_audio.
• Up to 120 seconds — Process source videos from 1 to 120 seconds.
• Up to 4K output — Choose 480p, 768p, 1080p, 2k, or 4k.

Parameters

How to Use

1. Upload a source video — Provide the video containing the person or people you want to replace.
2. Add reference photos — Upload one photo per person to replace.
3. Add a prompt optional — Describe who should be replaced when multiple people appear.
4. Choose a resolution — Select 480p, 768p, 1080p, 2k, or 4k.
5. Configure audio optional — Choose whether to preserve or use the source audio during generation.
6. Submit — Generate and retrieve the replaced video.

When replacing two people, use prompt to clarify which reference image corresponds to which person. Without a prompt, the reference images are matched from left to right.

Pricing

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

Example Costs

The number of reference images, prompt, save_audio, and ignore_audio do not add separate charges.

Best Use Cases

• Character replacement — Replace actors or people while preserving the original performance.
• Creative recasting — Reuse existing footage with different character appearances.
• Marketing content — Adapt existing video performances with new people.
• Social content — Create alternate character versions of existing clips.
• Multi-person replacement — Replace up to two people within the same source video.

Pro Tips

• Use clear reference photos with the subject’s face easily visible.
• Choose source footage where the people being replaced remain clearly visible.
• Use prompt when several people appear and the replacement order may be ambiguous.
• Keep ignore_audio=false when lip movements should follow the source speech.
• Use save_audio=true when the original soundtrack should remain in the final result.
• Use a fixed seed when comparing different settings or reference images.

Notes

• video and images are required.
• Supports 1 or 2 reference images.
• Source videos can be up to 120 seconds.Longer source videos use only the first 120 seconds.
• Supported source formats include MP4, MOV, and WebM.
• Source aspect ratio must be between 1:4 and 4:1.
• When ignore_audio=false, lip movements follow the source audio.
• When ignore_audio=true, lip movement is generated without using the source audio.

Related Models

• P-Video Replace — Replace people in existing videos using reference images.
• P-Video Upscale — Increase the resolution of existing videos while preserving their framing and soundtrack.

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",
  "save_audio": true,
  "ignore_audio": false
}
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/pruna-ai/p-video-2-pro/replace" \
  -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