Vosr2 Image API Documentation

Vosr2 Image API Documentation

Playground

VOSR2 Image Upscaler restores and upscales photos to 2K or 4K in a single pass, rebuilding fine structure, faces and small text with faithful color. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

VOSR2 Image Upscaler enlarges an input image to 2K or 4K while restoring fine visual detail in the same workflow. It is designed to improve hair, skin, foliage, fabric, small text, edges, and other high-frequency details while reducing blur and compression artifacts.

The input aspect ratio is preserved, making it suitable for photo restoration, portrait enhancement, product imagery, AI-generated images, and high-resolution display or print workflows.

Why Choose This?

• 2K and 4K upscaling
  Generate higher-resolution outputs directly at the selected target resolution.

• Detail restoration
  Recover fine structures such as hair, skin texture, fabric, foliage, edges, and small visual details.

• Artifact cleanup
  Reduce blur, compression artifacts, and softness during the upscale process.

• Aspect-ratio preservation
  Keep the original image composition and aspect ratio.

• Simple workflow
  Upload an image, choose the target resolution and output format, then generate the enhanced result.

• Fast processing
  Suitable for workflows where high-resolution output is needed without a lengthy restoration pipeline.

Parameters

How to Use

1. Provide an input image — Upload an image or provide its URL.
2. Choose target resolution — Select 2k or 4k.
3. Choose output format optional — Select jpeg, png, or webp.
4. Submit — Generate the upscaled and restored image.
5. Retrieve the result — Download the enhanced high-resolution output.

Pricing

Pricing is fixed at $0.01 per image.

target_resolution and output_format do not add separate charges.

Best Use Cases

• Photo restoration — Improve old, compressed, soft, or low-resolution photographs.
• Portrait enhancement — Restore facial, hair, clothing, and skin detail.
• Product imagery — Prepare product photos for e-commerce, advertising, or larger displays.
• AI-generated images — Upscale generated artwork before publishing, printing, or further editing.
• Print preparation — Create higher-resolution assets for posters, packaging, and physical media.
• Large-display output — Improve image quality for presentations, screens, and high-resolution viewing.

Pro Tips

• Use 2k when the source image is very small or when you want a more conservative upscale.
• Use 4k when you need maximum output resolution for print, display, or detailed viewing.
• Choose png when you want to avoid additional lossy compression.
• Photographs and natural images generally benefit most from detail restoration.
• For screenshots, charts, or flat graphics, inspect large uniform areas after upscaling because subtle texture may be introduced.
• If a very small source looks overly smooth at 4k, try 2k instead.

Notes

• image is required.
• target_resolution defaults to 4k.
• Supported target resolutions are 2k and 4k.
• output_format defaults to jpeg.
• Supported output formats are jpeg, png, and webp.
• The original aspect ratio is preserved.
• Very small inputs may require substantial enlargement, which can affect how much fine detail can be reconstructed.

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",
  "target_resolution": "4k",
  "output_format": "jpeg"
}
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/vosr2/image" \
  -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

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters