Pixverse Pixverse V5.5 Effects API Documentation

Pixverse Pixverse V5.5 Effects API Documentation

Playground

PixVerse V5.5 Effects is an AI image-to-video model that converts still images into smooth, natural short videos with lifelike motion, supporting 5s/8s/10s clips at 360p to 1080p for social posts, ads, and previews. Ready-to-use REST inference API, best performance, no cold starts, affordable pricing.

Features

PixVerse v5.5 Effects turns a single portrait into a short, stylised video with one-click cinematic presets. Pick looks like Kiss Me AI, Muscle Surge, Anything, Robot, The Tiger Touch, Holy Wings, Hulk, Venom, Microwave and more… then set resolution, duration, and aspect ratio for platform-ready clips.

See more video effects here!

Highlights

• Face-aware effects that keep the person’s identity while adding makeup, props, VFX and motion.
• Clean compositing & grading the effect feels shot in-camera, not pasted on top.
• Multiple aspect ratios (16:9, 1:1, 4:3, 3:4, 9:16) for feeds, stories, shorts and banners.
• Fast generation from 360p–1080p, with optional negative prompts to reduce artifacts.

Parameters

• image (required) – Portrait or bust shot (URL or upload).
• effect (required) – One of the curated presets (list above; may grow over time).
• resolution – 360p, 540p, 720p, 1080p.
• duration – 5s, 8s or 10s.
• negative_prompt (optional) – Avoid generate mentioned words. (e.g. watermark, text, distortion, extra limbs).

How to use

1. Upload a clear, front-facing portrait (avoid heavy occlusion or motion blur).
2. Choose an effect preset that matches the mood you want.
3. Set resolution (360p - 1080p), aspect_ratio, and duration (5s, 8s or 10s).
4. Tune control options

• Add a negative_prompt to explicitly block artefacts (e.g. “no watermark, no text”).

• Set thinking_type to enabled if you want the system to help refine/interpret a complex prompt; keep auto to let the model decide whether to turn on.

6. Click Run, then preview and download the generated clip.

Pricing

Tips

• Use evenly lit, front-facing portraits for the most stable, flattering effect.
• For casual social posts, 540p or 720p usually offers the best balance of speed and quality.
• For hero creatives or further editing in Non Linear Editors, pick 1080p and 8s.
• If hands, hair or edges look strange, try a different preset, a tighter crop, or add a short negative prompt (e.g. no extra hands, no warped hair).

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 Me AI",
  "resolution": "540p",
  "duration": 5,
  "thinking_type": "auto"
}
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.5-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

Conditional constraints

• When resolution is 1080p: duration must be one of 5, 8.
• When resolution is one of 360p, 540p, 720p: duration must be one of 5, 8, 10.

Response Parameters

Result Request Parameters

Result Response Parameters