Sam3 Image Rle API Documentation

Sam3 Image Rle API Documentation

Playground

SAM 3 RLE is a unified foundation model for promptable image segmentation using text, points, or boxes to detect and segment objects. Returns RLE (Run-Length Encoding) encoded masks for efficient storage and processing. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

SAM3 Image Segmentation RLE segments target objects in an image and returns mask data in RLE format. Use text prompts, point prompts, box prompts, or a combination of them to generate compact, program-friendly segmentation masks for API integration, automation, and computer-vision workflows.

Why Choose This?

• RLE mask output
  Return compact Run-Length Encoded mask data instead of a standard image mask.

• Multiple prompt types
  Segment objects using text prompts, point prompts, box prompts, or combined prompt guidance.

• Text-based target selection
  Describe what to segment with natural language, such as person, car, or background.

• Point and box control
  Use coordinates or bounding boxes when you need more precise target selection.

• API-friendly workflow
  Use structured mask data for automated pipelines, batch processing, annotation, and downstream editing.

• Low-cost segmentation
  Generate segmentation masks at a fixed price per image.

Parameters

At least one prompt type must be provided: prompt, point_prompts, or box_prompts.

How to Use

1. Upload an image — Provide the source image you want to segment.
2. Add a target prompt — Use a text prompt, point prompts, box prompts, or a combination of them.
3. Configure mask preview optional — Enable apply_mask when you want a visual mask overlay.
4. Submit — Generate the RLE segmentation result.

Output

The response returns RLE mask data in JSON format.

RLE means Run-Length Encoding. Instead of storing every mask pixel individually, it stores continuous runs of pixels, making the mask smaller and easier to use in automated image-processing pipelines.

Pricing

Pricing is fixed at $0.005 per image.

Image size, prompt type, point_prompts, box_prompts, and apply_mask do not add separate charges.

Best Use Cases

• ML data annotation — Generate segmentation masks for training datasets and annotation workflows.
• Automated pipelines — Integrate segmentation into batch image-processing systems.
• API integration — Use compact mask data in downstream services or custom applications.
• Computer vision workflows — Decode RLE masks for object isolation, measurement, or analysis.
• Background workflows — Generate masks for subject extraction or background processing.
• Large-scale segmentation — Process many images with lightweight structured mask outputs.

Pro Tips

• Use this endpoint when you need programmatic access to mask data.
• Use short, concrete prompts such as person, dog, car, or background.
• Use point prompts when text alone is ambiguous.
• Use box prompts when you need to constrain segmentation to a specific region.
• Combine text, points, and boxes when the target is difficult to isolate.
• Use standard RLE-compatible tooling to decode masks for downstream processing.

Notes

• image is required.
• At least one of prompt, point_prompts, or box_prompts must be provided.
• Output is RLE-encoded JSON, not a standard image file.
• RLE masks can be decoded into binary masks for editing, annotation, or computer-vision workflows.
• Point and box prompts use image coordinates.

Related Models

• SAM3 Image — Segment image targets and return direct image output.
• SAM3 Video Segmentation RLE — Segment video targets and return frame-level RLE mask data.
• SAM3 Video — Segment video targets and return direct video output.
• Bria RMBG — Remove image backgrounds for subject isolation workflows.

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",
  "apply_mask": true
}
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/wavespeed-ai/sam3-image-rle" \
  -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