Video Outpainter API Documentation

Video Outpainter API Documentation

Playground

WaveSpeedAI Video Outpainter expands any video beyond its original boundaries while preserving motion, identity, and scene coherence. Perfect for aspect-ratio changes, reframing, adding safe margins, or generating new visual context without cropping or losing content.

Features

What is Video Outpainter?

Video Outpainter expands your video outward in any direction, synthesizing new, coherent surroundings while preserving the original motion, characters, and scene continuity. It is ideal for reframing shots, adding safe margins, and converting aspect ratios (for example, 9:16 → 16:9) without cropping or losing key content.

Input Parameters

video (required)

The source video you want to expand. This defines all core motion, composition, and subject identity that the model will preserve.

prompt (optional)

A positive text description of how the newly generated surroundings should look. Examples:

• Extend skyline with modern city buildings
• Add a dense forest around the subject
• Fill the sides with a matching indoor studio background

If left empty, the model automatically generates a visually coherent extension based on the original footage.

aspect_ratio

Controls the aspect ratio of the outpainted output.

Available options:

• auto (default)
• 1:1, 4:3, 3:4
• 16:9, 9:16
• 3:2, 2:3
• 21:9, 9:21

Use this to widen or heighten shots, convert between social and cinematic formats, or create ultra-wide canvases.

seed

Controls randomness and reproducibility.

• −1 → a random seed is used for each run
• Any integer → repeatable results for the same inputs

Designed For

• Social teams – Export one master shot into multiple formats (TikTok, Shorts, Reels, YouTube, ads) without cropping faces or key actions.
• Editors and studios – Deliver different aspect ratios for clients, broadcast, or film-safe reframing from a single source clip.
• Marketing and ads – Repurpose existing assets for new placements by adding context and safe margins around the subject.
• Creators – Add cinematic space, environmental detail, or breathing room around shots while keeping the original take.

How to Use

1. Upload the video you want to outpaint.
2. Choose an aspect_ratio (auto or any supported cinematic/social ratio).
3. Optionally add a prompt to guide how the extended environment should look.
4. Set the seed (or leave it at −1 for variation).
5. Run the model, preview the result, and iterate until the framing and environment feel right.

Pricing

> Billing duration: Input media duration is rounded up to whole seconds. The minimum billed duration is 3 seconds; shorter inputs are billed as 3 seconds. Existing per-5-second rate tables remain unchanged.

Key Capabilities

• Expands video content in any direction (top, bottom, left, right).
• Converts aspect ratios without cropping the original frame.
• Preserves identity, motion, and temporal consistency across all frames.
• Generates natural, coherent backgrounds and surroundings that blend with the source video.
• Perfect for reframing, platform adaptation, and turning standard shots into more cinematic compositions.

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",
  "aspect_ratio": "auto",
  "seed": -1
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/video-outpainter" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL=$(printf '%s' "${TASK}" | jq -r '.urls.get // empty')
if [ -z "${RESULT_URL}" ]; then RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"; fi

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    created|processing) sleep 2 ;;
    *) printf 'Unexpected status: %s
' "${STATUS}" >&2; exit 1 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters