Pixverse Pixverse V5.5 Image To Video API Documentation

Pixverse Pixverse V5.5 Image To Video API Documentation

Playground

PixVerse V5.5 Image-to-Video turns a single image into cinematic clips with smooth motion, clean detail, and strong subject fidelity—ideal for logo stingers, character motion, and social posts. Ready-to-use REST inference API, best performance, no cold starts, affordable pricing.

Features

PixVerse v5.5 Image-to-Video animates a single image into a short cinematic clip. You provide a still frame plus a prompt; the model adds motion, camera moves, lighting changes and FX while keeping the original character, composition and style intact.

✨ Highlights

• Image-aware animation – Uses your input image as the first frame, preserving identity, pose and layout.
• Flexible formats – Resolutions from 360p–1080p and aspect ratios 16:9, 4:3, 1:1, 3:4, 9:16 for feeds, stories and banners.
• Multiple durations – Generate 5s, 8s or 10s clips for hooks, shorts or slightly longer moments.
• Prompt reasoning (thinking_type) – Optional system optimisation that can refine complex prompts before generation.

🧩 Parameters

• prompt* (string) Up to 2048 characters describing motion, camera, lighting and style. Example: “Dynamic anime close-up, wind blowing cloak and hair, camera slowly circling, sparks and glowing embers in the background.”

• image* (URL or upload) The source frame to animate. Front-facing, well-lit images work best.

• resolution One of 360p, 540p, 720p, 1080p.

• duration 5, 8 or 10 seconds.(10 seconds is not available for 1080p)

• thinking_type

• “enabled” – Turn on system-level reasoning to structure and optimise your prompt.

• “disabled” – Use your prompt exactly as written.

• “auto” (default) – Let the system decide whether to enable prompt optimizer automatically.

• negative_prompt (optional) Words you don’t want in the video, e.g. watermark, logo, text, distortion.

• seed (integer) Fix a seed for reproducible runs, or change it to get new variations from the same setup.

💰 Pricing

🚀 How to Use

1. Upload your image Add a clean, high-quality frame under image – ideally with clear subject and minimal motion blur.

2. Write the prompt Focus on how things move, camera path and overall mood, not on redesigning the character.

• Good: “Camera slowly pushes in, cloak flutters in the wind, sparks drift across frame, cinematic lighting.”
• Risky: “Change clothes and hairstyle completely while the character runs and transforms into a dragon.”

3. Choose resolution & ratio

• 16:9 for YouTube / landscape.
• 9:16 for TikTok / Reels / Stories.
• 1:1 or 4:3 for feed posts.

4. Set duration and resolution

• Select resolution from 360p,540p,720p,1080p
• Select duration from 5s, 8s or 10s (Not available for 1080p)

5. (Optional) Adjust thinking_type, negative_prompt and seed

• Use enabled or auto for complex, multi-sentence prompts. The model will optimize it for you to generate better video output.
• Add a short negative prompt to avoid artefacts.
• Lock the seed while you tweak small details.

6. Run and iterate Generate the clip, review motion and framing, then refine your prompt or duration as needed.

💡 Best Practices

• Keep the image and prompt aligned – don’t describe a totally different scene or character.
• Use medium or close shots for character-focused animations; wide shots can feel sparse.
• For platforms with heavy compression, prefer 720p / 1080p to keep details clean.
• Avoid overloading the prompt with too many actions; 1–3 clear motions usually work best.

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",
  "resolution": "540p",
  "duration": 5,
  "generate_audio_switch": false,
  "generate_multi_clip_switch": false,
  "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/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

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