AI Image Processing (GPU)

Five model-backed endpoints, all dispatched to a shared GPU worker. They are asynchronous internally but synchronous to you — the HTTP call blocks until the image is processed.

Method Endpoint Model Typical latency
GET /image/remove-bg U²-Net / IS-Net 2–6 s
GET /image/upscale Real-ESRGAN 5–30 s
GET /image/describe BLIP 1–4 s
GET /image/colorize Deep-learning colouriser 3–10 s
GET /image/face-restore GFP-GAN 3–10 s

Path prefix caveat. These five GPU routes are registered without a /v1 prefix (apis/image/app/routers/gpu.py builds a bare APIRouter() and main.py mounts it with app.include_router(gpu.router)), unlike every other image router which uses prefix="/v1". So from the app itself the live paths are /image/*. Behind the production gateway that adds /v1, they appear as /v1/image/*. If you get a 404, try both. The GPU routes also skip the verify_auth dependency the other image routers carry — treat that as a known inconsistency, not something to rely on.

All five take the image as a query parameter (url), not a JSON body. It must be a publicly reachable URL — private IPs, localhost and file:// are rejected. Maximum length 2048 characters.

Every response is the worker's output object merged with status: "ok" and task_id. The result image itself is returned via a hosted URL or a storage key, not inline in the response.

Self-hosters: these endpoints return 503 unless the GPU worker is enabled and reachable. See Error cases.

1. Background removal

GET /image/remove-bg?url=... (or /v1/image/remove-bg via the gateway)

Parameters

Name In Type Default Notes
url query string — Public image URL (required, ≤2048 chars)
model query enum u2net u2net, u2net_human_seg, isnet
alpha_matting query boolean false Soft edges around hair/fur; slower, more memory

Model choice matters more than any other parameter:

Model Best for Trade-off
u2net Products, objects, generic photos Fast; can keep thin stray structures
u2net_human_seg People, portraits, avatars Poor on non-human subjects
isnet Complex edges, semi-transparency Slowest, best mattes
curl "https://image.toolkitapi.io/v1/image/remove-bg?url=https://example.com/photo.jpg&model=u2net_human_seg&alpha_matting=true" \
  -H "X-API-Key: YOUR_KEY"
import requests

def remove_background(url: str, model: str = "isnet") -> dict:
    r = requests.get(
        "https://image.toolkitapi.io/v1/image/remove-bg",
        headers={"X-API-Key": "YOUR_KEY"},
        params={"url": url, "model": model, "alpha_matting": True},
        timeout=180,
    )
    r.raise_for_status()
    data = r.json()
    # Result is a PNG with transparent background, referenced by URL
    return {"url": data.get("url"), "task_id": data["task_id"]}

print(remove_background("https://example.com/photo.jpg"))
const params = new URLSearchParams({
  url: "https://example.com/photo.jpg",
  model: "u2net_human_seg",
  alpha_matting: "true",
});

const resp = await fetch(`https://image.toolkitapi.io/v1/image/remove-bg?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) throw new Error(`remove-bg failed: ${resp.status}`);
const data = await resp.json();
console.log(data.task_id, data.url ?? data.output_minio_key);
Response
{
  "status": "ok",
  "url": "https://cdn.toolkitapi.io/gpu/9a1f2c/remove-bg.png",
  "format": "png",
  "task_id": "gpu-9a1f2c"
}
The exact set of output keys is defined by the GPU worker and may also include `output_minio_key` instead of `url`. Always read the image location defensively:
location = data.get("url") or data.get("output_minio_key")

2. AI upscaling

GET /v1/image/upscale?url=...

Name In Type Default Notes
url query string — Public image URL
scale query integer 2 2 or 4 only
model query enum realesrgan-x4plus realesrgan-x4plus, realesrgan-x4plus-anime
face_enhance query boolean false Run GFP-GAN face enhancement after upscaling

Use realesrgan-x4plus-anime only for illustration/anime art — it distorts photographic faces.

curl "https://image.toolkitapi.io/v1/image/upscale?url=https://example.com/small.jpg&scale=4&model=realesrgan-x4plus&face_enhance=true" \
  -H "X-API-Key: YOUR_KEY"
import requests

r = requests.get(
    "https://image.toolkitapi.io/v1/image/upscale",
    headers={"X-API-Key": "YOUR_KEY"},
    params={
        "url": "https://example.com/small.jpg",
        "scale": 2,
        "face_enhance": False,
    },
    timeout=300,  # 4× upscales of large images are slow
)
r.raise_for_status()
data = r.json()
print(data.get("url"), data.get("width"), data.get("height"))
const params = new URLSearchParams({
  url: "https://example.com/small.jpg",
  scale: "4",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/upscale?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { url, width, height, task_id } = await resp.json();
console.log(task_id, width && `${width}×${height}`, url);

Real-ESRGAN is generative: output is sharp but not a faithful reconstruction. Don't use it where pixel accuracy matters (medical, legal evidence, OCR sources — OCR the original instead).

3. Captioning / description

GET /v1/image/describe?url=...

Name In Type Default Notes
url query string — Public image URL
detail_level query enum medium short, medium, long
generate_tags query boolean false Additionally return keyword tags
curl "https://image.toolkitapi.io/v1/image/describe?url=https://example.com/chart.png&detail_level=long&generate_tags=true" \
  -H "X-API-Key: YOUR_KEY"
import requests

cap = requests.get(
    "https://image.toolkitapi.io/v1/image/describe",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"url": "https://example.com/chart.png", "detail_level": "medium"},
    timeout=120,
).json()

print(cap.get("description"))
# Good as an alt-text seed, not as final copy
const params = new URLSearchParams({
  url: "https://example.com/chart.png",
  detail_level: "medium",
  generate_tags: "true",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/describe?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const { description, tags } = await resp.json();
console.log(description, tags);

BLIP output is a short natural-language description. It does not reliably read text in the image — use Document Intelligence OCR for that.

4. Colourisation

GET /v1/image/colorize?url=...

Name In Type Required Notes
url query string yes Public URL of a grayscale or sepia image
curl "https://image.toolkitapi.io/v1/image/colorize?url=https://example.com/old-photo.jpg" \
  -H "X-API-Key: YOUR_KEY"
import requests

r = requests.get(
    "https://image.toolkitapi.io/v1/image/colorize",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"url": "https://example.com/old-photo.jpg"},
    timeout=180,
)
r.raise_for_status()
print(r.json().get("url"))
const resp = await fetch(
  "https://image.toolkitapi.io/v1/image/colorize?url=" +
    encodeURIComponent("https://example.com/old-photo.jpg"),
  { headers: { "X-API-Key": "YOUR_KEY" } },
);
console.log((await resp.json()).url);

Feeding an already-colourful image produces desaturated, muddy output. Check saturation client-side if users can upload arbitrary files.

5. Face restoration

GET /v1/image/face-restore?url=...

Name In Type Default Notes
url query string — Public image URL containing faces
upscale query integer 1 Face upscale factor: 1, 2, or 4
curl "https://image.toolkitapi.io/v1/image/face-restore?url=https://example.com/lowres-portrait.jpg&upscale=2" \
  -H "X-API-Key: YOUR_KEY"
import requests

r = requests.get(
    "https://image.toolkitapi.io/v1/image/face-restore",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"url": "https://example.com/lowres-portrait.jpg", "upscale": 2},
    timeout=180,
)
r.raise_for_status()
print(r.json().get("url"))
const params = new URLSearchParams({
  url: "https://example.com/lowres-portrait.jpg",
  upscale: "2",
});
const resp = await fetch(`https://image.toolkitapi.io/v1/image/face-restore?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const out = await resp.json();
console.log(out.url ?? out.task_id);

GFP-GAN only works when a face is detected. Images with no face — or faces smaller than roughly 32 px — fail the task rather than passing through unchanged.

Error cases

Status Condition detail
503 GPU processing disabled in this deployment GPU image processing is disabled
503 Worker enabled but not reachable GPU task API is currently unavailable
504 Worker exceeded its time budget GPU task timed out (<reason>)
500 Worker failed, e.g. no face detected GPU task failed: <reason>
422 Missing url, url over 2048 chars, or invalid enum value (scale=3, model=foo) FastAPI validation error
401/403 Missing or invalid API key auth error
{ "detail": "GPU task API is currently unavailable" }

The two 503 variants are worth distinguishing: disabled is permanent until an operator changes config (don't retry), unavailable is transient capacity (retry with backoff).

Note that an invalid model or scale value produces 422, not a silent fallback — unlike many "smart" APIs, these enums are strict.

Tips

  • Pick the model deliberately. Default u2net on a portrait produces ragged hair edges; u2net_human_seg on a product shot can delete the product. isnet is the safe generalist when you can afford latency.
  • Set generous client timeouts. 30 s covers describe/colorize; use 300 s for 4× upscales and 180 s for background removal with alpha_matting.
  • alpha_matting is not free. It roughly doubles processing time and can fail on very large images. Enable it only when edges are visible against a contrasting background.
  • Upscale before you matte, not after. Removing a background from an already-upscaled image gives cleaner edges than the reverse.
  • face_enhance cuts both ways. It makes portraits pop and can make non-portrait upscales look uncanny — keep it off by default.
  • Generative upscaling invents detail. Never treat Real-ESRGAN or GFP-GAN output as evidence of what was in the original.
  • Results are hosted artefacts. Copy them to your own storage if you need retention; don't assume the GPU output URL is permanent.
  • Queue client-side rather than firing in parallel. GPU capacity is shared; 20 concurrent upscale calls will mostly time out. Cap concurrency at 2–4.
  • Retry 503/504 with backoff; never retry 500 — a failed task is deterministic for the same input.