API reference/POST /remove-url

Remove background from URL

Same as /remove but the source image lives at a URL we fetch on your behalf. Skip the upload step when the image is already public.

POSThttps://useknockout--api.modal.run/remove-url

Parameters

Send as multipart/form-data unless noted otherwise.

urlrequiredstring—Public URL of the source image. HTTPS required. ≤10 MB after fetch.
formatstringpngOutput format — png (with alpha) or webp.
qualityint 1-10092JPEG/WebP quality. Ignored for PNG.

Request

curl -X POST "https://useknockout--api.modal.run/remove-url" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/cat.jpg","format":"png"}' \
  -o out.png

Response

HTTP/1.1 200 OK
content-type: image/png
content-length: 254312
x-knockout-latency: 184
x-knockout-model: BiRefNet
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

Errors

401unauthorized—Missing or invalid token.
402payment_required—Free tier exhausted. Add a card to continue.
413payload_too_large—Image exceeds 10 MB or 4096×4096.
422no_subject_detected—Foreground could not be isolated from background.
429rate_limit_exceeded—Slow down. Retry-After header tells you when.
500internal_error—Something broke on our side. Include request_id when reporting.
424fetch_failed—We couldn't fetch the source URL. Check it's public and HTTPS.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • We fetch via HTTP GET with a 10s timeout, no redirects beyond the first.
  • Fetched bytes count against your quota same as direct uploads.
← POST /removePOST /replace-bg →