GitHub - useknockout/api

State-of-the-art background removal API — open source, self-hostable, 40× cheaper than remove.bg.

Live API · Docs · Quick Start · API Reference · Self-hosting

Drop an image in. Get a transparent PNG out. ~200ms per call.

kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f

curl -X POST "https://useknockout--api.modal.run/remove" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@your-image.jpg" \
  -o out.png

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

# solid color background
curl -X POST "https://useknockout--api.modal.run/replace-bg" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@cat.jpg" \
  -F "bg_color=#FF5733" \
  -F "format=jpg" \
  -o out.jpg

# use a remote image as the new background
curl -X POST "https://useknockout--api.modal.run/replace-bg" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@cat.jpg" \
  -F "bg_url=https://example.com/mountains.jpg" \
  -o out.png

# multipart batch
curl -X POST "https://useknockout--api.modal.run/remove-batch?format=png" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "files=@a.jpg" -F "files=@b.jpg" -F "files=@c.jpg"

# URL batch — JSON body
curl -X POST "https://useknockout--api.modal.run/remove-batch-url" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://a.jpg","https://b.jpg"], "format":"png"}'

# Sticker — cutout + thick white outline (WhatsApp / iMessage sticker style)
curl -X POST "https://useknockout--api.modal.run/sticker" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -F "stroke_width=24" -o sticker.png

# Smart crop — tight bounding box around subject
curl -X POST "https://useknockout--api.modal.run/smart-crop" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -F "padding=32" -o cropped.png

# Studio shot — e-commerce preset (white bg + shadow + centered, 1:1 aspect)
curl -X POST "https://useknockout--api.modal.run/studio-shot" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -F "aspect=1:1" -F "format=jpg" -o studio.jpg

# Shadow — subject composited onto new bg with a drop shadow
curl -X POST "https://useknockout--api.modal.run/shadow" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -F "bg_color=#F3F4F6" -o shadow.png

# Compare — before/after side-by-side for marketing/social
curl -X POST "https://useknockout--api.modal.run/compare" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -o compare.png

# Mask — just the black/white mask, for your own pipeline
curl -X POST "https://useknockout--api.modal.run/mask" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -o mask.png

# Outline — subject on transparent bg with a thin outline
curl -X POST "https://useknockout--api.modal.run/outline" \
  -H "Authorization: Bearer kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f" \
  -F "file=@photo.jpg" -F "outline_color=#000000" -F "outline_width=4" -o outline.png

curl https://useknockout--api.modal.run/health
# {"status":"ok","model":"ZhengPeng7/BiRefNet"}

{
  "url": "https://example.com/image.jpg",
  "format": "png"
}

{
  "count": 3,
  "format": "png",
  "results": [
    { "filename": "a.jpg", "success": true, "format": "png", "size_bytes": 124503, "data_base64": "..." },
    { "filename": "b.jpg", "success": true, "format": "png", "size_bytes": 98321, "data_base64": "..." },
    { "filename": "c.jpg", "success": false, "error": "Invalid or unsupported image" }
  ]
}

{
  "urls": ["https://example.com/a.jpg", "https://example.com/b.jpg"],
  "format": "png"
}

import requests

URL = "https://useknockout--api.modal.run/remove"
TOKEN = "kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f"  # public beta token

with open("input.jpg", "rb") as f:
    resp = requests.post(
        URL,
        headers={"Authorization": f"Bearer {TOKEN}"},
        files={"file": f},
    )
resp.raise_for_status()

with open("output.png", "wb") as f:
    f.write(resp.content)

import { writeFile } from "node:fs/promises";
import { Knockout } from "@useknockout/node";

const client = new Knockout({ token: process.env.KNOCKOUT_TOKEN! });

// 1. Remove background → transparent PNG
const png = await client.remove({ file: "./input.jpg" });
await writeFile("out.png", png);

// 2. Replace background with a color
const jpg = await client.replaceBackground({
  file: "./input.jpg",
  bgColor: "#FF5733",
  format: "jpg",
});
await writeFile("out.jpg", jpg);

// 3. Replace background with a remote image
const composed = await client.replaceBackground({
  file: "./input.jpg",
  bgUrl: "https://example.com/mountains.jpg",
});

// 4. Batch — process 10 URLs in one call
const batch = await client.removeBatchUrl({
  urls: ["https://example.com/a.jpg", "https://example.com/b.jpg"],
});
for (const r of batch.results) {
  if (r.success) await writeFile(`out-${r.url}.png`, Buffer.from(r.data_base64!, "base64"));
}

import { readFile, writeFile } from "node:fs/promises";

const URL = "https://useknockout--api.modal.run/remove";
const TOKEN = process.env.KNOCKOUT_TOKEN;

const buf = await readFile("input.jpg");
const form = new FormData();
form.set("file", new Blob([buf]), "input.jpg");

const res = await fetch(URL, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },
  body: form,
});
if (!res.ok) throw new Error(await res.text());

await writeFile("output.png", Buffer.from(await res.arrayBuffer()));

export async function removeBackground(file: File, token: string) {
  const form = new FormData();
  form.append("file", file);

  const res = await fetch("https://useknockout--api.modal.run/remove", {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    body: form,
  });

  if (!res.ok) throw new Error(`knockout error: ${res.status}`);
  return await res.blob(); // PNG with alpha
}

package main

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func removeBG(path, token string) ([]byte, error) {
    f, err := os.Open(path)
    if err != nil { return nil, err }
    defer f.Close()

    body := &bytes.Buffer{}
    w := multipart.NewWriter(body)
    part, _ := w.CreateFormFile("file", path)
    io.Copy(part, f)
    w.Close()

    req, _ := http.NewRequest("POST",
        "https://useknockout--api.modal.run/remove", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", w.FormDataContentType())

    resp, err := http.DefaultClient.Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

curl -X POST "https://useknockout--api.modal.run/remove?format=webp" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@input.jpg" \
  -o output.webp

pip install modal
modal token new

git clone https://github.com/useknockout/api.git
cd api

# create your bearer-token secret
modal secret create knockout-secrets API_TOKEN=$(openssl rand -hex 32)

# deploy
modal deploy main.py

@app.cls(
    gpu="L4",              # or "A10", "A100", "H100"
    scaledown_window=60,   # seconds of idle before scale-to-zero
    max_containers=10,     # max concurrent containers
)

┌────────────┐      HTTPS       ┌───────────────────────────┐
│   Client   │ ───────────────▶ │  Modal ASGI (FastAPI)     │
│ (any lang) │                  │  ┌─────────────────────┐  │
└────────────┘                  │  │ Auth (bearer)       │  │
                                │  │ Validation          │  │
                                │  │ Image decode (PIL)  │  │
                                │  │ BiRefNet on L4 GPU  │  │
                                │  │ Encode (PNG/WebP)   │  │
                                │  └─────────────────────┘  │
                                │  Scale-to-zero, auto-HTTPS │
                                └───────────────────────────┘