Pixverse Pixverse V5 Effects API Documentation

Pixverse Pixverse V5 Effects API Documentation

Playground

PixVerse V5 Effects converts images into smooth, natural short videos with lifelike motion; supports 5s/8s and 720p/1080p outputs. Ready-to-use REST API, no coldstarts, best performance, affordable pricing.

Features

PixVerse v5 Effects turns a single portrait into a short, stylized video with one-click cinematic effects. Choose from curated presets (e.g., Kiss Me AI, Muscle Surge, Anything, Robot, The Tiger Touch, Holy Wings, Hulk, Venom, Microwave), then set resolution, duration, and aspect ratio for platform-ready outputs.

Highlights

• Face-aware effects that preserve identity while adding makeup, props, VFX, and motion.
• Clean compositing and color grading matched to each preset’s look.
• Multiple aspect ratios (16:9, 1:1, 4:3, 3:4, 9:16) for feeds, stories, and banners.
• Fast iteration at 360p–1080p with optional negative prompts to avoid artifacts.

Parameters

• image (required): portrait or bust shot, URL or upload.
• effect (required): pick an effect preset (examples above; catalog may expand).
• resolution: 360p, 540p, 720p, 1080p.
• duration: 5s or 8s.
• aspect_ratio: 16:9, 1:1, 4:3, 3:4, 9:16.
• negative_prompt (optional): terms to avoid (e.g., watermark, text, distortion).

How to Use

1. Upload image (clear face, minimal occlusion works best).
2. Select an effect preset that matches your vibe.
3. Choose resolution, aspect ratio, and duration (5s or 8s).
4. (Optional) Add a negative prompt to suppress unwanted artifacts.
5. Click Run and download your clip.

Pricing

Pricing depends on the selected resolution, video duration, and sound effects setting.

Billing Rules

• Each request generates one video. Prices above are total charges per request.
• Without sound effects, an 8-second video costs twice as much as a 5-second video at the same resolution.
• Sound effects add $0.01 per second: $0.05 for 5 seconds or $0.08 for 8 seconds.
• Sound effects are enabled by default. Set sound_effect_switch to false to disable them.
• The default configuration (540p, 5 seconds, sound effects enabled) costs $0.275.

Tips

• Use even, front-facing portraits for the most stable effects.
• For subtle looks, keep resolution at 540p or 720p and add a short negative prompt.
• For hero shots or export to edit suites, render at 1080p and 8s.
• If hands or hair look off, try a different effect preset or a tighter crop.

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",
  "effect": "Kiss",
  "resolution": "540p",
  "duration": 5,
  "sound_effect_switch": true
}
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/pixverse/pixverse-v5-effects" \
  -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