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
/v1prefix (apis/image/app/routers/gpu.pybuilds a bareAPIRouter()and main.py mounts it withapp.include_router(gpu.router)), unlike every other image router which usesprefix="/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 a404, try both. The GPU routes also skip theverify_authdependency 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
503unless 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
u2neton a portrait produces ragged hair edges;u2net_human_segon a product shot can delete the product.isnetis 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_mattingis 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_enhancecuts 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
upscalecalls will mostly time out. Cap concurrency at 2–4. - Retry
503/504with backoff; never retry500— a failed task is deterministic for the same input.
Related endpoints¶
- Image Analysis — EXIF, dimensions, dominant colours (CPU, fast)
- Generation & Watermarking — placeholders, QR codes, watermarks
- PDF Document Intelligence — OCR and field extraction from images