Entwicklerdoku

MiniPic bietet zwei API-Schichten: eine Kompatibilitätsschicht (mit Authentifizierung und Antwortstruktur, die mit gängigen Komprimierungs-APIs kompatibel sind – durch bloßen Austausch von Endpunkt und Schlüssel integrieren) und eine native Schicht (/v1/*, synchrone Komprimierung und Nutzungsabfragen). Du zahlst nur für erfolgreiche Komprimierungen, die ersten 500 jeden Monat sind kostenlos, jede Antwort trägt Nutzungs-Header, und deine Rechnung ist Zeile für Zeile nachvollziehbar.

Stabilitätsversprechen: Breaking Changes an /shrink und /v1 werden 90 Tage im Voraus angekündigt.

Schnellstart

Komprimiere dein erstes Bild in 30 Sekunden: erstelle einen API-Schlüssel in der Konsole und sende dann eine Anfrage.

# Ein PNG komprimieren (Basic-Auth, Benutzername fest auf api) curl -s --user api:DEIN_API_SCHLÜSSEL \ --data-binary @input.png \ -o output.png \ https://api.minipic.ai/v1/compress

Das Ergebnis wird über einen verschlüsselten privaten Link bereitgestellt, auf den nur du, der Schlüsselinhaber, zugreifen kannst – Bilder werden ausschließlich für diese Komprimierung verwendet, durchgehend verschlüsselt, niemals weitergegeben und niemals für Training oder andere Zwecke genutzt.

Authentifizierung

HTTP Basic (kompatibel mit gängigen Komprimierungs-APIs): Benutzername fest auf api, Passwort ist dein API-Schlüssel – Authorization: Basic base64("api:KEY")
Bearer (empfohlen für die native Schicht): Authorization: Bearer KEY

Schlüsselpräfixe sind mp_live_ (Produktion) und mp_test_ (Sandbox); der Server speichert nur einen Hash des Schlüssels, und der vollständige Schlüssel wird nur einmal bei der Erstellung angezeigt. Jedes Konto kann bis zu 5 Schlüssel halten. Authentifizierungsfehler geben immer 401 zurück, ohne die Ursache zu unterscheiden (um Enumeration zu verhindern).

POST /shrink Ein Bild komprimieren

Der Anfragetext ist eine von zwei Optionen: ein rohes binäres Bild (PNG / JPEG / WebP / HEIC / GIF / BMP / TIFF / AVIF) oder JSON, das eine Quell-URL angibt (nur öffentliche http/https-Adressen, 10 Sekunden Abruf-Timeout). Wenn kein Ausgabeformat angegeben ist, wird das Originalformat beibehalten: PNG / JPEG / WebP / GIF / TIFF / AVIF werden im Originalformat ausgegeben (AVIF→AVIF, TIFF→TIFF); HEIC wird in JPEG umgewandelt; BMP, das im eigenen Format nicht komprimiert werden kann, wird in PNG umgewandelt. GIF wird standardmäßig verlustfrei optimiert (bleibt GIF) und kann auch in WebP umgewandelt werden, um mehr zu sparen.

# Option 1: Binärdatei direkt hochladen curl -s --user api:DEIN_API_SCHLÜSSEL \ --data-binary @input.png \ https://api.minipic.ai/shrink

# Option 2: den Server eine URL abrufen lassen curl -s --user api:DEIN_API_SCHLÜSSEL \ -H "Content-Type: application/json" \ -d '{"source": {"url": "https://example.com/input.png"}}' \ https://api.minipic.ai/shrink

Bei Erfolg gibt es 201 Created zurück, mit Antwort-Headern inklusive Location (die Ergebnisadresse) und Compression-Count (diesen Monat abgerechnete Bilder):

{ "input": { "size": 207565, "type": "image/png" }, "output": { "size": 63274, "type": "image/png", "width": 1280, "height": 720, "ratio": 0.3049, "url": "https://api.minipic.ai/output/{id}" } }

GET /output/{id} Das Ergebnis herunterladen

Erfordert Authentifizierung; gibt die Binärdatei des komprimierten Ergebnisses zurück. Ergebnisse werden über einen verschlüsselten privaten Link bereitgestellt; sobald der Link abläuft, gibt es 404 OutputExpired zurück, und du kannst erneut komprimieren, um es wieder zu erhalten. Das erneute Herunterladen desselben Ergebnisses wird nicht berechnet.

POST /output/{id} Abgeleitete Operationen

Führe resize / convert / preserve auf ein komprimiertes Ergebnis aus; jede abgeleitete Ausgabe zählt als 1 Bild:

# Proportional auf 800 px Breite skalieren und in WebP umwandeln curl -s --user api:DEIN_API_SCHLÜSSEL \ -H "Content-Type: application/json" \ -d '{"resize": {"method": "scale", "width": 800}, "convert": {"type": "image/webp"}}' \ -o thumb.webp \ https://api.minipic.ai/output/{id}

resize.method: scale (proportional einseitig) / fit (vollständig einpassen) / cover (füllend zuschneiden, derzeit zentrierter Zuschnitt)
convert.type: zwischen image/webp, image/png und image/jpeg umwandeln
preserve: Metadaten copyright / creation / location beibehalten

Aktuelle Einschränkungen (vor der Integration lesen): thumb intelligente Thumbnails sind noch nicht verfügbar (gibt 501 NotImplemented zurück); cover ist ein zentrierter Zuschnitt (intelligente Motiverkennung ist geplant); AVIF-Ausgabe wird nicht unterstützt; direkter store-Upload zu S3/GCS wird nicht unterstützt (direkter Upload zu Objektspeicher ist geplant).

POST /v1/compress Synchrone Komprimierung (native Schicht)

Eine einzelne Anfrage gibt die Binärdatei des komprimierten Ergebnisses direkt zurück und spart einen Roundtrip – praktisch für CI:

# Qualitäts-Voreinstellung und Ausgabeformat werden über Query-Parameter gesetzt curl -s -H "Authorization: Bearer DEIN_API_SCHLÜSSEL" \ --data-binary @input.jpg \ -o output.jpg \ "https://api.minipic.ai/v1/compress?quality=smart&format=keep"

quality: smart (Standard) / high / extreme / 1-100
format: keep (Originalformat beibehalten) / webp
Antwort-Header: X-Input-Size / X-Output-Size / X-Ratio / Compression-Count

GET /v1/usage Nutzungsabfrage

Gibt die Anzahl dieses Monats, das verbleibende Gratiskontingent und das verbleibende Guthaben des Ressourcenpakets zurück – identisch zur Konsole:

{ "month": "2026-06", "compressed": 1234, "free_quota": { "total": 500, "used": 500 }, "bundles": [ { "id": "...", "total": 10000, "remaining": 5210 } ], "pay_as_you_go": { "count": 734, "estimated_amount_cny": "36.70" }, "rate_limit": { "rps": 10, "burst": 20 } }

Kontingente und Ratenbegrenzungen

Rate: 10 Anf./s pro Schlüssel, Burst 20 (Token-Bucket); bei Überschreitung gibt es 429 + Retry-After zurück
Parallelität: laufende Aufgaben pro Schlüssel <= 20
Kostenloses Monatskontingent: 500 Bilder/Monat/Konto; sobald aufgebraucht und keine Zahlung hinterlegt, gibt es 429 AccountLimitReached zurück
Pro Datei: 5 MB kostenlos; 80 MB kostenpflichtig; für Enterprise anpassbar
Pixel: <= 100 Megapixel; bei Überschreitung gibt es 422 ImageTooComplex zurück

Antwort-Header auf allen abgerechneten Endpunkten: Compression-Count, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Abrechnung

POST /shrink Erfolg (201): zählt als 1 Bild
POST /v1/compress Erfolg (200): zählt als 1 Bild
GET /output/{id} erneutes Herunterladen: nicht berechnet
POST /output/{id} erfolgreiche abgeleitete Operation: zählt jedes Mal als 1 Bild
4xx / 5xx, Blockierungen durch Inhaltsprüfung und URL-Abruffehler: nicht berechnet; bei einem erfolgreichen erneuten Versuch zählt nur der erfolgreiche Aufruf

Abbuchungsreihenfolge: monatliches Plan-Kontingent → Ressourcenpakete (zuerst gekauft, zuerst verbraucht, verfallen nie). Prepaid, ohne nutzungsbasierte Monatsabrechnung – sobald das Kontingent aufgebraucht ist, pausiert es, und der Kauf eines Ressourcenpakets stellt es wieder her.

AI- / Skill-Integration

MiniPic bietet einen offiziellen Agent Skill (minipic-compress): einmal installiert, sage einem beliebigen AI-Agenten, der den offenen Standard der Anthropic Agent Skills unterstützt (Claude Code / Cursor / Codex CLI / Copilot CLI usw.), etwas wie „komprimiere die Bilder in diesem Ordner“, und er ruft automatisch die MiniPic-API auf, um zu komprimieren, in WebP umzuwandeln, im Stapel zu verarbeiten und das Komprimierungsverhältnis zu melden – ohne von Hand curl oder Retry-Logik schreiben zu müssen.

Installation

Wähle eine der folgenden Möglichkeiten (drei Optionen):

# Option 1: über skills.sh (npx, empfohlen) npx skills add minipic/minipic-skill

# Option 2: über gh skill gh skill install minipic/minipic-skill

# Option 3: manuell in das Skills-Verzeichnis legen (Claude Code Benutzer-/Projektebene) cp -r minipic-compress ~/.claude/skills/ # Oder auf Projektebene: cp -r minipic-compress <dein-projekt>/.claude/skills/

Für andere Agenten, die den Agent-Skills-Standard unterstützen (Cursor / Codex CLI / Copilot CLI usw.), folge deren Doku, um das Verzeichnis minipic-compress/ in den entsprechenden Skills-Pfad zu legen.

Deinen API-Schlüssel konfigurieren

Der Schlüssel wird nur aus einer Umgebungsvariablen gelesen und wird nie fest einkodiert oder ausgegeben. Nachdem du einen Schlüssel in der Konsole erstellt hast, setze ihn in deiner Umgebung:

# Erforderlich: dein API-Schlüssel (500 kostenlose Bilder/Monat/Konto) export MINIPIC_API_KEY=mp_live_dein_schlüssel # Optional: die API-Basis-URL überschreiben (Standard https://api.minipic.ai) # export MINIPIC_API_BASE=https://api.minipic.ai

Geltungsbereich und Auslöser-Beispiele

Der Skill wird automatisch ausgelöst, wenn du Absichten wie diese äußerst:

„Komprimiere dieses Bild / die Bilder in diesem Ordner“
„Wandle hero.png in WebP um und mach es so klein wie möglich“
„Diese Bilder sind zu groß – optimiere sie im Stapel vor dem Packen und sag mir, wie viel ich gespart habe“

Fähigkeiten: Komprimierung von Einzeldatei / Ordner-Stapel / Remote-URL, Umwandlung zwischen PNG·JPEG·WebP·GIF, Auswahl der Qualitäts-Voreinstellung (smart / high / extreme), automatische Berechnung und Meldung des Ersparnis-Prozentsatzes und automatischer Back-off-Retry bei 429-Ratenbegrenzung.

VS-Code-Erweiterung

Die offizielle Erweiterung MiniPic Image Compression lässt dich Workspace-Bilder direkt in deinem Editor komprimieren, ohne von Hand curl, angetrieben von der selbst entwickelten MiniPic-Engine. Sie unterstützt PNG / JPEG / WebP / GIF / AVIF / TIFF und kann beim Komprimieren das Format umwandeln (etwa in WebP / AVIF, um mehr zu sparen), und funktioniert in VS Code, Cursor und anderen kompatiblen Editoren.

Installation

Wähle eine der folgenden Möglichkeiten:

Suche im VS-Code-Erweiterungs-Panel (⇧⌘X) nach MiniPic und klicke auf Installieren;
oder führe ext install minipic.minipic-vscode über die Befehlspalette aus;
oder besuche die Visual-Studio-Marketplace-Erweiterungsseite und klicke auf Installieren.

Deinen API-Schlüssel konfigurieren

Nachdem du in der Konsole einen Schlüssel (beginnend mit mp_live_) erstellt hast, führe MiniPic: Set API Key über die Befehlspalette (⇧⌘P) aus und füge ihn ein. Der Schlüssel wird sicher im VS Code SecretStorage gespeichert und wird nie in eine Klartext-Konfiguration geschrieben oder über settings.json synchronisiert.

So wird's benutzt

Per Rechtsklick komprimieren: wähle im Explorer Bilder oder Ordner aus (einzeln, mehrfach oder ein ganzes Verzeichnis rekursiv) → Rechtsklick MiniPic: Compress Images, um an Ort und Stelle mit den aktuellen Qualitäts- und Formateinstellungen zu komprimieren.
In WebP umwandeln und Referenzen aktualisieren: Rechtsklick MiniPic: Convert to WebP and Update References, um in WebP umzuwandeln und dabei automatisch die Referenzen auf dieses Bild im gesamten Workspace zu aktualisieren.
Auto-Komprimierung: wenn aktiviert, überwacht sie neue/geänderte Workspace-Bilder und komprimiert sie automatisch (standardmäßig aus, da sie Kontingent verbraucht); umschalten über die Statusleiste oder mit MiniPic: Toggle Auto-Compress.
Nutzung ansehen: führe MiniPic: View Usage aus, um die komprimierte Anzahl dieses Monats, das kostenlose Guthaben und die Nutzungsschätzung zu sehen – identisch zur Konsole.

Häufige Einstellungen

Einstellung	Standard	Beschreibung
`minipic.quality`	`smart`	Qualitäts-Voreinstellung: smart / high / extreme / lossless
`minipic.format`	`keep`	Ausgabeformat: keep / png / jpeg / webp / gif / avif / tiff
`minipic.skipIfLarger`	`true`	Überspringen und das Original nicht überschreiben, wenn eine Komprimierung im selben Format es größer macht
`minipic.keepOriginalOnConvert`	`true`	Die Originaldatei beim Umwandeln des Formats behalten
`minipic.maxFileSizeMB`	`80`	Dateien überspringen, die größer als diese Größe sind, um 413 zu vermeiden
`minipic.baseUrl`	`https://api.minipic.ai`	API-Serviceadresse; ändere sie auf dein eigenes Gateway für selbst gehostete Bereitstellungen

Die Erweiterung wird über dieselbe Bildkompressions-API abgerechnet – eine erfolgreiche Komprimierung zählt als 1 Bild und genießt dasselbe kostenlose Monatskontingent; die Nutzung ist identisch zur Konsole. Quellcode auf GitHub.

Fehlercodes

Der Fehlertext folgt der Konvention gängiger Komprimierungs-APIs: {"error": "code", "message": "menschenlesbare Beschreibung"}; Felder werden nur hinzugefügt, nie entfernt.

HTTP	error	Auslöser	Beschreibung
400	`BadRequest`	Empty body, invalid JSON, or out-of-range parameters	Something was off with this request, so the image was not compressed. Try again, and contact [email protected] if it keeps happening.
400	`InputMissing`	Request body has no image content	This file is empty, so there is nothing to compress. Check the file and upload it again.
401	`Unauthorized`	Missing, invalid, or disabled key	This API key is invalid or disabled. Double-check the key, or create a new one in the console.
403	`AccountSuspended`	Account banned or overdue	This account has been suspended. Contact [email protected] if you think this is a mistake.
404	`NotFound`	Wrong path	We could not find what you requested. Check that the link is correct.
404	`OutputExpired`	Result private link has expired	This private result link has expired and can no longer be opened. Upload the image again to recompress it.
413	`PayloadTooLarge`	Exceeds the plan's per-file size limit	This image is over the 5 MB per-file limit on the free plan. Upgrade to Pro to compress files up to 80 MB.
415	`UnsupportedMediaType`	Input is not a supported image format	This format is not supported yet. We currently support PNG, JPEG, WebP, HEIC, GIF, BMP, TIFF and AVIF.
422	`DecodeError`	Corrupt file or spoofed extension	We could not decode this image: the file may be corrupted or not a valid image. Check it and upload again.
422	`ImageTooComplex`	Exceeds the 100-megapixel limit	This image is over the 100-megapixel processing limit. Resize it smaller and try again.
422	`ContentBlocked`	Blocked by content safety screening (not billed)	This image did not pass our content safety check. It was blocked and permanently deleted, and was not counted against your usage. If you believe this is a mistake, contact [email protected].
429	`TooManyRequests`	Rate or concurrency limit exceeded (with Retry-After)	Too many requests right now, so this image could not be queued. Wait a moment and try again.
429	`AccountLimitReached`	Free quota used up and no payment on file (with upgrade_url)	You have used up today's free quota. Sign in to remove the daily limit (1,000 images per month); Pro raises the per-file limit to 80 MB.
500	`InternalServerError`	Service error (with request_id)	Something went wrong on our side and this image was not compressed. Please try again shortly.
501	`NotImplemented`	Capability not yet available (such as resize thumb)	This feature is not available yet. Watch the developer docs for updates.
503	`ServiceUnavailable`	Overloaded or under maintenance (with Retry-After)	The service is busy and this image was not compressed. Please try again shortly.