Sam3 Video API Documentation

Sam3 Video API Documentation

Playground

SAM3 Video is a unified foundation model for prompt-based video segmentation. Provide text, point, box, or mask prompts and the model segments and tracks targets across frames with strong temporal consistency. Supports concept-level (“segment anything with concepts”) and multi-object masks for editing, analytics, and VFX. Ready-to-use REST inference API with fast response, no cold starts, and affordable pricing.

Features

WaveSpeedAI SAM3 Video Video-to-Video is a prompt-based video segmentation and mask-guided editing model. Provide a video and a short text prompt to target specific subjects across frames, then choose whether to apply the mask to the video output or return a mask-style result for downstream workflows.

Why Choose This?

• Prompt-based target selection
  Use natural language to identify the subject or object to segment, such as person, woman, red car, or backpack.

• Multi-object targeting
  Target multiple objects in one request by listing them in the prompt.

• Mask-guided video output
  Use apply_mask to control whether the detected mask is applied to the video or returned as a mask-style output.

• Temporal video consistency
  Track selected subjects across frames for more stable video segmentation workflows.

• Editing and compositing workflows
  Prepare masks or localized video outputs for object removal, background cleanup, subject isolation, and downstream compositing.

Parameters

How to Use

1. Upload a video — Provide the source video you want to process.
2. Write a target prompt — Describe the subject or object to segment, such as the woman, red car, or person, backpack.
3. Choose mask behavior — Keep apply_mask enabled to apply the mask to the video output. Disable it when you need a black-and-white mask-style output.
4. Submit — Generate the processed video result.

Pricing

Pricing is based on input video duration.

Billed duration is rounded up to the next whole second, with a minimum billed duration of 3 seconds and a maximum billed duration of 600 seconds. Pricing is charged in 5-second units at $0.05 per 5 seconds.

prompt and apply_mask do not add separate charges.

Best Use Cases

• Video segmentation — Segment people, objects, animals, clothing, vehicles, or other visible subjects across frames.
• Subject isolation — Isolate a target subject for compositing or downstream editing.
• Mask generation — Create black-and-white mask-style video outputs for external editing pipelines.
• Object-focused editing — Prepare localized regions for removal, cleanup, or replacement workflows.
• Background cleanup — Target foreground subjects or unwanted background objects with prompt guidance.
• Multi-target workflows — Segment multiple objects in one run when the prompt clearly identifies each target.

Pro Tips

• Use short, concrete target descriptions for better segmentation.
• For multiple objects, use comma-separated labels such as person, backpack, bicycle.
• Keep the prompt focused on what should be targeted.
• Use apply_mask=true when you want the mask applied to the video output.
• Use apply_mask=false when you need a black-background mask output with the selected region shown in white.
• Use stable footage with clear subject separation for better results.
• Reduce the number of targets if the model selects the wrong object or drifts across frames.

Notes

• video and prompt are required.
• apply_mask defaults to true.
• When apply_mask is disabled, the output is a mask-style video with a black background and the selected region in white.
• Billed duration is rounded up and clamped to 3–600 seconds.
• Very short videos are billed as 3 seconds.
• Videos longer than 600 seconds are billed at the 600-second cap.

Related Models

• WaveSpeedAI Video Eraser — Remove unwanted objects or people from videos using mask-based guidance.
• Wan 2.2 Video Edit — Edit video content with text instructions.
• WaveSpeedAI Video Watermark Remover — Remove logos, captions, or watermarks from videos.
• WaveSpeedAI Video Outpainter — Expand video borders for reframing and aspect-ratio changes.

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",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "apply_mask": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/sam3-video" \
  -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="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 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|deleted) 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