Zum Inhalt springen
BlocCut
API-Key holen
REST · HTTP · MCP

BlocCut API

Server in Deutschland

Entfernt den Hintergrund eines Bildes und gibt es mit echtem Alpha-Kanal zurück — als PNG oder WebP. Ein KI-Modell liefert die Maske; die brauchbare Kante entsteht danach aus Guided Filter, Farbschätzung und daraus nachgezogenem Alpha. Gerechnet wird auf einem Server in Deutschland.

Braucht den DE-Inferenz-Server, Upload max. 4,5 MB

Die Freistellung läuft auf einem KI-Inferenz-Server in Deutschland. Ist er überlastet oder in Wartung, kommt 502 oder 504 zurück — abgerechnet wird nur bei Erfolg. Außerdem nimmt die Hosting-Plattform (Vercel) höchstens 4,5 MB Request-Body an und liefert höchstens 4,5 MB Response-Body, obwohl BlocCut Bilder bis 15 MB verarbeitet — größere Dateien gehen über MCP mit image_url, dann lädt unser Server die Datei selbst (interne Netze sind gesperrt).

Endpunkt

POSThttps://cut.bloc-apps.com/api/v1/remove

  • Body: rohe Bild-Bytes (image/png, image/jpeg, image/webp)
  • Antwort: ein Bild mit Alpha-Kanal — image/png oder image/webp, je nach format
  • Preis: 5 ct pro Bild (50 Operationen im Monat frei)

Authentifizierung

Header Authorization: Bearer blk_live_…. Keys erstellst du im Dashboard. Ein Key lässt sich auf dieses eine Tool beschränken und mit einem eigenen Monats-Limit versehen.

Idempotenz

Sende einen Idempotency-Key mit. Er steht für genau einen Vorgang.

Wird derselbe Schlüssel ein zweites Mal gesendet, antwortet die API mit 409 und führt die Verarbeitung nicht erneut aus. So kann dieselbe Anfrage weder doppelt abgerechnet noch — durch Wiederverwendung des Schlüssels — kostenlos wiederholt werden.

Für jeden neuen Vorgang einen neuen Schlüssel senden (etwa crypto.randomUUID()). Ohne Header erzeugen wir selbst einen. Wir speichern keine Ergebnisse — eine verlorene Antwort lässt sich deshalb nicht nachträglich abholen.

Parameter

Alle Parameter werden als Query-String an die URL gehängt.

NameWerteStandardBedeutung
formatpng · webpautomatischOhne Angabe wählt der Dienst selbst die verlustfreieste Kodierung, die noch unter die 4,5-MB-Antwortgrenze der Plattform passt (PNG → verlustfreies WebP → WebP). Das ist nötig, weil die Größe eines freigestellten PNG fast nur am Bildrauschen hängt: dasselbe Motiv mit 6,25 MP wiegt glatt 4,4 MB und mit Kamerarauschen 15 MB. Wer ein bestimmtes Format braucht, setzt es ausdrücklich — dann gilt es ohne Wenn und Aber. Beide Formate tragen einen echten Alpha-Kanal; Content-Type und der Kopf X-Bloc-Encoding sagen, was es geworden ist.

Antwort-Header

Jede erfolgreiche Antwort sagt, was sie verbraucht hat:

  • X-Bloc-Ops — verbrauchte Kontingent-Einheiten dieser Anfrage (bei einem Bild: 1)
  • X-Bloc-Overage-Ops — davon über dem Monatskontingent (0, solange Kontingent übrig ist)
  • X-Bloc-Source — included (im Kontingent) · overage (auf die Monatsrechnung) · free (im Browser, kostenlos)

Fehler

401API-Key fehlt, ist ungültig oder wurde widerrufen
402Monatskontingent des Plans (oder das Limit dieses Keys) erreicht
409Idempotency-Key wurde schon verwendet — der Vorgang lief bereits
413Datei zu groß (Bytes oder Pixel/Seiten)
415Dateiformat wird nicht unterstützt
429Rate-Limit je API-Key — je nach Plan 20 bis 120 Anfragen pro Minute
502 / 504Verarbeitung fehlgeschlagen oder Zeitüberschreitung

Der Body enthält immer error (Maschinen-Code) und message (deutscher Klartext).

Beispiel — curl

curl -X POST "https://cut.bloc-apps.com/api/v1/remove?format=webp" \
  -H "Authorization: Bearer blk_live_DEIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary "@portrait.png" \
  --output ergebnis

Beispiel — JavaScript

const res = await fetch("https://cut.bloc-apps.com/api/v1/remove?format=webp", {
  method: "POST",
  headers: {
    Authorization: "Bearer blk_live_DEIN_KEY",
    "Content-Type": file.type,
    // Ein neuer Schlüssel pro Vorgang. Derselbe Schlüssel zweimal → 409.
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: file,
});

if (res.status === 402) throw new Error("Monatskontingent aufgebraucht");
if (!res.ok) throw new Error((await res.json()).message);

console.log("verbraucht:", res.headers.get("X-Bloc-Ops"), "Operation(en)");
const ergebnis = await res.blob();

Als KI-Werkzeug (MCP)

BlocCut ist auch über den Bloc-Apps-MCP-Server nutzbar. Claude und andere Assistenten rufen es dann selbst auf — über dasselbe Konto und Kontingent. Einrichtung im Dashboard unter „API & KI“.

bloccut_remove_background

Entfernt den Hintergrund eines Bildes und liefert es mit Alpha-Kanal zurück. Eingabe als Base64 oder https-URL.

Eingabe

  • image_base64 (string) — Bild als Base64 (ohne data:-Präfix).
  • image_url (string) — Öffentliche https-URL des Bildes. Der Weg für Dateien über 4,5 MB — unser Server lädt sie selbst (interne Netze sind gesperrt).
  • format (string) — png (Standard) oder webp. Der Schlüssel im Ergebnis heißt nach dem Format — png_base64 bzw. webp_base64 —, damit die Datei nicht mit falscher Endung auf der Platte landet.

Rückgabe

{ png_base64 } bzw. { webp_base64 } plus ops, billable_ops, cost_cents und source.

API-Dokumentation · BlocCut