Fazit vorab: SmartSlim Server bietet eine RESTful-API mit vier Hauptschnittstellen – Upload-Komprimierung, Batch-Komprimierung, Statusabfrage und Callback-Benachrichtigung – und unterstützt API-Key- und Bearer-Token-Authentifizierung. Die Upload-Komprimierung einer 100MB-PDF dauert ca. 8 Sekunden, die Batch-Komprimierung von 100 Dateien ca. 12 Sekunden. Standard-Rate-Limit: 60 Anfragen pro Minute, Enterprise bis 300. Dieser Artikel bietet Parameterdetailtabellen für alle vier Schnittstellen, Python/JavaScript/curl-Aufrufbeispiele und Fehlerbehandlungsstrategien. Im Folgenden wird mit einem API-Überblick begonnen und jede Schnittstelle detailliert erläutert.
Wenn Sie das SDK lokal integrieren möchten statt HTTP-API-Aufrufe zu verwenden, lesen Sie zunächst Komprimierungs-SDK-Integrationsleitfaden: Python/Java/C# Multi-Language.
1. API-Schnittstellenübersicht
Die RESTful-API des SmartSlim Server basiert auf dem FastAPI-Framework, alle Schnittstellen geben JSON-Daten zurück und unterstützen multipart/form-data-Datei-Uploads. Der API-Basispfad lautet /api/v1/, alle Anfragen müssen Authentifizierungsinformationen enthalten.
| Schnittstelle | Methode | Pfad | Funktion | Sync/Async |
|---|---|---|---|---|
| Upload-Komprimierung | POST | /api/v1/compress | Einzeldatei hochladen und komprimieren | Sync (unter 50MB)/Async |
| Batch-Komprimierung | POST | /api/v1/compress/batch | Mehrere Dateien hochladen und komprimieren | Async |
| Statusabfrage | GET | /api/v1/status/{task_id} | Komprimierungsaufgabenstatus abfragen | Sync |
| Callback-Benachrichtigung | POST | Client-Callback-URL | Aktive Benachrichtigung nach Abschluss | Async-Push |
Es gibt zwei Authentifizierungsmethoden: API-Key-Authentifizierung für Server-Aufrufe und Bearer-Token-Authentifizierung für Frontend-Aufrufe. Die folgende Tabelle vergleicht die Merkmale beider Methoden.
| Authentifizierungsmethode | Anfrage-Header | Gültigkeit | Anwendungsszenario | Sicherheit |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | Dauerhaft (widerrufbar) | Server-Aufrufe | Mittel (HTTPS erforderlich) |
| Bearer Token | Authorization: Bearer token | 24 Stunden | Frontend-Aufrufe | Hoch (kurzlebig) |
2. Schnittstellenparameter im Detail
1. Upload-Komprimierungsschnittstelle
Die Upload-Komprimierungsschnittstelle empfängt eine einzelne Datei und gibt das Komprimierungsergebnis zurück. Bei Dateien unter 50MB wird synchron ein Download-Link zurückgegeben, bei über 50MB asynchron eine Task-ID.
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| file | multipart/file | Ja | - | Zu komprimierende Datei |
| format | string | Nein | Auto-Erkennung | Dateityp (pdf/image/ofd) |
| level | string | Nein | medium | Komprimierungsstufe (low/medium/high/ultra) |
| quality | integer | Nein | 75 | Qualitätsfaktor (1-100) |
| callback_url | string | Nein | - | Async-Callback-Benachrichtigungs-URL |
2. Batch-Komprimierungsschnittstelle
Die Batch-Komprimierungsschnittstelle empfängt mehrere Dateien, verarbeitet asynchron und gibt eine Batch-Task-ID zurück. Die Parallelitätszahl kann angegeben werden, die maximale Parallelität wird durch die Lizenz beschränkt.
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| files | multipart/file[] | Ja | - | Liste der zu komprimierenden Dateien (max. 100) |
| level | string | Nein | medium | Komprimierungsstufe |
| quality | integer | Nein | 75 | Qualitätsfaktor |
| workers | integer | Nein | 4 | Parallelitätszahl (1-16) |
| callback_url | string | Nein | - | Abschluss-Callback-URL |
3. Statusabfrageschnittstelle
Die Statusabfrageschnittstelle fragt über die Task-ID den aktuellen Status und das Ergebnis einer asynchronen Komprimierungsaufgabe ab.
| Rückgabefeld | Typ | Beschreibung |
|---|---|---|
| task_id | string | Eindeutige Task-Kennung |
| status | string | Status (pending/processing/completed/failed) |
| progress | integer | Fortschritt in Prozent (0-100) |
| download_url | string | Download-Link des Ergebnisses (nach Abschluss) |
| original_size | integer | Ursprüngliche Dateigröße (Bytes) |
| compressed_size | integer | Komprimierte Größe (Bytes) |
| error | string | Fehlermeldung (bei Fehlschlag) |
3. Aufrufbeispiele für drei Sprachen
Im Folgenden werden Aufrufbeispiele für curl, Python und JavaScript gezeigt, jeweils am Beispiel der Upload-Komprimierung einer einzelnen PDF-Datei.
| Sprache | Kern-Code | Beschreibung |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | Kommandozeilen-Aufruf |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | requests-Bibliothek |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
4. Rate-Limiting und Fehlerbehandlung
Die API verfügt über ein vollständiges Rate-Limiting- und Fehlerbehandlungssystem. Das Verständnis der HTTP-Statuscodes und Fehlercodes ist Voraussetzung für robusten Aufrufcode.
| HTTP-Statuscode | Fehlercode | Bedeutung | Behandlungsempfehlung |
|---|---|---|---|
| 200 | - | Erfolg | Response-Daten parsen |
| 400 | INVALID_PARAM | Parameterfehler | Anfrageparameter prüfen |
| 401 | UNAUTHORIZED | Authentifizierung fehlgeschlagen | API-Key/Token prüfen |
| 413 | FILE_TOO_LARGE | Datei zu groß | Chunk-Upload verwenden |
| 429 | RATE_LIMITED | Zu viele Anfragen | Exponential-Backoff-Retry |
| 500 | INTERNAL_ERROR | Serverfehler | Wiederholen oder Support kontaktieren |
| 503 | SERVICE_UNAVAILABLE | Dienst nicht verfügbar | Nach Wartezeit wiederholen |
Rate-Limiting-Details: Standardmäßig 60 Anfragen pro Minute, 10 gleichzeitige pro Sekunde; Enterprise 300 pro Minute, 30 gleichzeitige pro Sekunde. Bei Überschreitung wird 429 zurückgegeben, der Response-Header enthält X-RateLimit-Remaining (verbleibende Anfragen) und X-RateLimit-Reset (Reset-Zeitstempel). Empfohlen wird clientseitiger Exponential-Backoff: Nach 429 1 Sekunde warten und wiederholen, bei erneutem Fehlschlagen 2 Sekunden, dann 4 Sekunden, maximal 3 Wiederholungen.
| Dateityp | Ursprüngliche Größe | Komprimierte Größe | Komprimierungsdauer | Komprimierungsrate |
|---|---|---|---|---|
| PDF (Scan) | 80MB | 8,2MB | 6,5s | 89,8% |
| PDF (elektronisch) | 15MB | 3,1MB | 1,2s | 79,3% |
| JPEG-Bild | 12MB | 2,8MB | 0,8s | 76,7% |
| PNG-Bild | 25MB | 6,5MB | 1,5s | 74,0% |
| OFD-Dokument | 30MB | 5,2MB | 2,0s | 82,7% |
Wenn Sie mehr über das zugrundeliegende Designprinzip der Komprimierungs-Task-Queue erfahren möchten, siehe Design der Komprimierungs-Task-Queue. Wenn Sie den API-Dienst per Docker bereitstellen möchten, siehe Docker-Bereitstellung des Komprimierungsdienstes.
5. Häufig gestellte Fragen (FAQ)
F1: Wie authentifiziert man Komprimierungs-API-Aufrufe?
Die Komprimierungs-API des SmartSlim Server unterstützt zwei Authentifizierungsmethoden: API-Key-Authentifizierung (Schlüssel im Anfrage-Header X-API-Key, geeignet für Server-Aufrufe) und Bearer-Token-Authentifizierung (JWT-Token im Authorization-Header, geeignet für Frontend-Aufrufe). API-Keys sind dauerhaft gültig aber jederzeit widerrufbar, Tokens gelten 24 Stunden und müssen regelmäßig erneuert werden. Für Produktionsumgebungen wird die API-Key-Methode empfohlen – einfach und zuverlässig.
F2: Welche Dateiformate unterstützt die Komprimierungs-API?
Die Server-Edition-API von SmartSlim unterstützt PDF, Bilder (jpg/jpeg/tif) und OFD-Formate, mit einer Dateigrößenobergrenze von 1GB. Die Cloud-Edition-API unterstützt alle 10 Kategorien und 40+ Formate (inkl. Video, Audio, Office-Dokumente usw.), mit einer Obergrenze von 10GB pro Datei. Beim Aufruf wird der Dateityp über den format-Parameter angegeben; wird dieser nicht übergeben, erfolgt eine automatische Erkennung. Hinweis: Die Server-Edition unterstützt nur PDF/Bilder/OFD, für alle Formate ist die Cloud-Edition erforderlich.
F3: Gibt es Aufruflimits für die Komprimierungs-API?
Zum Schutz der Dienststabilität gibt es Rate-Limiting-Strategien. Standard-Limit: 60 Anfragen pro Minute, 10 gleichzeitige pro Sekunde. Bei Überschreitung wird Statuscode 429 zurückgegeben, der Response-Header enthält X-RateLimit-Remaining und X-RateLimit-Reset. Die Enterprise-Edition kann auf 300 Anfragen pro Minute und 30 gleichzeitige pro Sekunde erhöht werden. Es wird empfohlen, clientseitig einen Exponential-Backoff-Retry-Mechanismus zu implementieren – nach Erhalt von 429 mit 1-2-4 Sekunden inkrementell wiederholen.
F4: Wie verarbeitet die Komprimierungs-API große Dateien?
Für große Dateien (über 50MB) wird die Chunk-Upload-Schnittstelle empfohlen: Die Datei wird in mehrere 5MB-Chunks aufgeteilt und hochgeladen, nach Abschluss wird die Zusammenführung und Komprimierung angestoßen. Nach Abschluss wird das Ergebnis über Callback-Benachrichtigung oder Statusabfrage-Schnittstelle abgerufen. Die Komprimierung großer Dateien erfolgt asynchron und blockiert nicht den API-Aufruf. Eine 100MB-PDF dauert ca. 8 Sekunden, ein 1GB-Video ca. 90 Sekunden, danach wird automatisch ein Download-Link generiert.
Zusammenfassung
Die RESTful-API des SmartSlim Server bietet vier Hauptschnittstellen – Upload-Komprimierung, Batch-Komprimierung, Statusabfrage und Callback-Benachrichtigung – und deckt das gesamte Spektrum von Einzeldatei- bis Batch-Verarbeitung ab. Authentifizierung wahlweise: API-Key für Server, Bearer-Token für Frontend. Rate-Limiting klar definiert: Standard 60 pro Minute, Enterprise 300, Statuscode 429 mit Exponential-Backoff-Retry. Eine 80MB-Scan-PDF wird in 6,5 Sekunden auf 8,2MB komprimiert, Rate 89,8%.
Drei Punkte zum Merken: Erstens unter 50MB synchrone Rückgabe des Ergebnisses, darüber asynchron mit Task-ID-Abfrage; zweitens bei 429-Rate-Limit Exponential-Backoff-Retry implementieren, nicht einfach weiter probieren; drittens große Dateien über die Chunk-Upload-Schnittstelle in 5MB-Stücken hochladen. Mit den richtigen Schnittstellen und Parametern ist der API-Aufruf eigentlich ganz einfach. Wenn Sie eher lokales SDK als HTTP bevorzugen, siehe den Komprimierungs-SDK-Integrationsleitfaden.
Verwandte Artikel
Dateien komprimieren? Probieren Sie SmartSlim
Basierend auf einer selbstentwickelten Rust-Komprimierungs-Engine, unterstützt 10 Kategorien und über 40 Formate, darunter PDF, Bilder, Video, Office und OFD, mit lokaler Komprimierung, die Ihre Daten vor Ort behält.