Pixverse Pixverse V6 Max Image To Video API Documentation

Pixverse Pixverse V6 Max Image To Video API Documentation

Playground

PixVerse V6 Max Image-to-Video generates high-quality videos from input images with flexible duration, 360P to 1080P output, seed control, optional native audio generation, multi-clip generation, sound-effect prompts for creative, social, marketing, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

PixVerse V6 Max Image-to-Video animates a reference image into a video with prompt-guided motion, camera movement, and optional generated audio. Upload an image, describe how the scene should move, then choose the duration and resolution up to 1080p.

Why Choose This?

• Image-to-video generation — Animate portraits, products, landscapes, illustrations, and other reference images.
• Up to 1080p output — Choose 360p, 540p, 720p, or 1080p.
• Prompt-guided motion — Describe subject movement, camera behavior, lighting, and scene progression.
• Optional generated audio — Add native audio to the generated video.
• Sound-effect control — Provide sound-effect guidance for supported generation workflows.
• Multi-clip generation — Enable multiple shots or scene changes within a generation.
• Seed control — Use a fixed seed when comparing prompt variations.

Parameters

How to Use

1. Upload an image — Provide the reference image to animate.
2. Write a prompt — Describe subject motion, camera movement, lighting, and visual style.
3. Choose output settings — Set duration and resolution.
4. Configure generated audio optional — Enable generated audio or add sound-effect guidance when needed.
5. Enable multi-clip optional — Use multi-clip generation for multiple shots or scene changes.
6. Set a seed optional — Use a fixed seed when reproducibility is useful.
7. Submit — Generate and retrieve the completed video.

Pricing

Pricing is based on the selected resolution, duration, and whether generated audio is enabled.

Other generation settings do not add separate charges.

Best Use Cases

• Portrait animation — Bring people and characters in still images into motion.
• Product videos — Animate product photography for advertising and social content.
• Creative concepts — Turn illustrations and concept art into moving scenes.
• Marketing content — Create campaign and promotional clips from existing visuals.
• Audio-visual content — Add generated sound and sound effects.
• Multi-shot storytelling — Create scenes that benefit from multiple shots or transitions.

Pro Tips

• Start with a clear, high-quality reference image.
• Focus the prompt on movement, action, camera behavior, and scene progression.
• Use sound_effect_content to describe specific sounds rather than visual details.
• Use lower resolutions for quick testing before moving to 720p or 1080p.
• Enable multi-clip generation when the scene needs multiple shots.
• Use a fixed seed when comparing prompt or setting changes.

Notes

• image and prompt are required.
• duration supports 1–15 seconds and defaults to 5.
• resolution defaults to 720p.
• generate_audio_switch defaults to false.
• generate_multi_clip_switch defaults to false.
• sound_effect_switch defaults to false.
• A fixed seed can help compare variations but does not guarantee identical results.

Related Models

• PixVerse V6 Max Text-to-Video — Generate videos directly from text prompts without a reference image.
• PixVerse V6 Max Image-to-Video — Animate a reference image with prompt-guided motion and optional generated 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'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "resolution": "720p",
  "duration": 5,
  "generate_audio_switch": false,
  "generate_multi_clip_switch": false,
  "sound_effect_switch": 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/pixverse/pixverse-v6-max/image-to-video" \
  -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