Conclusion d'abord : SmartSlim Server fournit une API RESTful comprenant 4 interfaces principales — compression par upload, compression par lot, interrogation de statut, notification par callback — prenant en charge deux méthodes d'authentification : API Key et Bearer Token. La compression par upload d'un PDF de 100 Mo prend environ 8 secondes, la compression par lot de 100 fichiers environ 12 secondes. La limitation de débit par défaut est de 60 requêtes par minute, pouvant être portée à 300 pour la version entreprise. Cet article fournit les tableaux de paramètres détaillés des 4 interfaces, des exemples d'appels Python/JavaScript/curl et des solutions de gestion des erreurs. Commençons par un aperçu de l'API, puis détaillons chaque interface.
Si vous avez besoin d'une intégration SDK locale plutôt que d'appels via API HTTP, nous vous recommandons de lire d'abord Guide d'intégration du SDK de compression : appels multilangues Python/Java/C#。
I. Vue d'ensemble de l'API
L'API RESTful de SmartSlim Server est développée sur le framework FastAPI. Toutes les interfaces renvoient des données au format JSON et prennent en charge le téléchargement de fichiers en multipart/form-data. Le chemin de base de l'API est /api/v1/, et toutes les requêtes doivent comporter des informations d'authentification.
| Interface | Méthode | Chemin | Fonction | Synchrone/Asynchrone |
|---|---|---|---|---|
| Compression par upload | POST | /api/v1/compress | Télécharge un seul fichier et le compresse | Synchrone (moins de 50 Mo)/Asynchrone |
| Compression par lot | POST | /api/v1/compress/batch | Télécharge plusieurs fichiers et les compresse | Asynchrone |
| Interrogation de statut | GET | /api/v1/status/{task_id} | Interroge le statut de la tâche de compression | Synchrone |
| Notification par callback | POST | URL de callback client | Notifie activement après la compression | Push asynchrone |
Deux méthodes d'authentification : l'authentification API Key est adaptée aux appels côté serveur, l'authentification Bearer Token aux appels côté front-end. Le tableau ci-dessous compare les caractéristiques des deux méthodes.
| Méthode d'authentification | En-tête de requête | Validité | Cas d'usage | Sécurité |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | Permanent (révocable) | Appels côté serveur | Moyenne (HTTPS requis) |
| Bearer Token | Authorization: Bearer token | 24 heures | Appels côté front-end | Élevée (validité courte) |
II. Détail des paramètres de chaque interface
1. Compression par uploadInterface
L'interface de compression par upload reçoit un seul fichier et renvoie le résultat de compression. Pour les fichiers de moins de 50 Mo, le lien de téléchargement du fichier compressé est renvoyé de manière synchrone ; pour les fichiers de plus de 50 Mo, un identifiant de tâche est renvoyé de manière asynchrone.
| Paramètre | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| file | multipart/file | Oui | - | Fichier à compresser |
| format | string | Non | Détection automatique | Type de fichier (pdf/image/ofd) |
| level | string | Non | medium | Niveau de compression (low/medium/high/ultra) |
| quality | integer | Non | 75 | Facteur de qualité (1-100) |
| callback_url | string | Non | - | AsynchroneNotification par callbackURL |
2. Compression par lotInterface
L'interface de compression par lot reçoit plusieurs fichiers, les traite de manière asynchrone et renvoie un identifiant de tâche par lot. Elle permet de spécifier le nombre de concurrents, le maximum étant limité par la licence.
| Paramètre | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| files | multipart/file[] | Oui | - | Liste de fichiers à compresser (100 maximum) |
| level | string | Non | medium | Niveau de compression |
| quality | integer | Non | 75 | Facteur de qualité |
| workers | integer | Non | 4 | Nombre de concurrents (1-16) |
| callback_url | string | Non | - | URL de callback de fin |
3. Interrogation de statutInterface
L'interface d'interrogation de statut permet de consulter l'état actuel et les résultats d'une tâche de compression asynchrone via l'identifiant de tâche.
| Champ de retour | Type | Description |
|---|---|---|
| task_id | string | Identifiant unique de tâche |
| status | string | Statut (pending/processing/completed/failed) |
| progress | integer | Pourcentage de progression (0-100) |
| download_url | string | Lien de téléchargement du résultat (après completion) |
| original_size | integer | Taille du fichier original (octets) |
| compressed_size | integer | Taille après compression (octets) |
| error | string | Message d'erreur (en cas d'échec) |
III. Exemples d'appels en trois langages
Voici des exemples d'appels en curl, Python et JavaScript, tous basés sur la compression par upload d'un seul fichier PDF.
| Langage | Code principal | Description |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | Appel en ligne de commande |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | Bibliothèque requests |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
IV. Limitation de débit et gestion des erreurs
L'API dispose d'un mécanisme complet de limitation de débit et de gestion des erreurs. Comprendre les codes d'état HTTP et les codes d'erreur est essentiel pour écrire un code d'appel robuste.
| Code d'état HTTP | Code d'erreur | Signification | Suggestion de traitement |
|---|---|---|---|
| 200 | - | Succès | Analyser les données de réponse |
| 400 | INVALID_PARAM | Erreur de paramètre | Vérifier les paramètres de requête |
| 401 | UNAUTHORIZED | Échec d'authentification | Vérifier l'API Key/le Token |
| 413 | FILE_TOO_LARGE | Fichier trop volumineux | Utiliser le téléchargement par blocs |
| 429 | RATE_LIMITED | Requêtes trop fréquentes | Reprendre avec backoff exponentiel |
| 500 | INTERNAL_ERROR | Erreur serveur | Reprendre ou contacter le support |
| 503 | SERVICE_UNAVAILABLE | Service indisponible | Reprendre après attente |
Détails de la stratégie de limitation de débit : par défaut 60 requêtes par minute, 10 concurrents par seconde ; la version entreprise passe à 300 requêtes par minute et 30 concurrents par seconde. En cas de dépassement, le code 429 est renvoyé, les en-têtes de réponse contiennent X-RateLimit-Remaining (nombre restant) et X-RateLimit-Reset (horodatage de réinitialisation). Il est recommandé que le client implémente un backoff exponentiel : après réception d'un 429, attendre 1 seconde avant de reprendre, puis 2 secondes, puis 4 secondes, avec un maximum de 3 tentatives.
| Type de fichier | Taille originale | Taille après compression | Temps de compression | Taux de compression |
|---|---|---|---|---|
| PDF (document numérisé) | 80 Mo | 8,2 Mo | 6,5 s | 89,8 % |
| PDF (version électronique) | 15 Mo | 3,1 Mo | 1,2 s | 79,3 % |
| Image JPEG | 12 Mo | 2,8 Mo | 0,8 s | 76,7 % |
| Image PNG | 25 Mo | 6,5 Mo | 1,5 s | 74,0 % |
| Document OFD | 30 Mo | 5,2 Mo | 2,0 s | 82,7 % |
Si vous souhaitez comprendre les principes de conception sous-jacents de la file d'attente des tâches de compression, vous pouvez consulter Conception de la file d'attente des tâches de compression. Si vous avez besoin de déployer le service API via Docker, vous pouvez consulter Déploiement Docker du service de compression。
V. FAQ
Q1：Comment s'authentifier pour appeler l'API de compression ?
L'API de compression de SmartSlim Server prend en charge deux méthodes d'authentification : l'authentification par API Key (transmission de la clé dans l'en-tête X-API-Key, adaptée aux appels côté serveur) et l'authentification par Bearer Token (transmission d'un jeton JWT dans l'en-tête Authorization, adaptée aux appels côté front-end). L'API Key est permanente mais peut être révoquée à tout moment, le Token a une validité de 24 heures et doit être rafraîchi régulièrement. En production, la méthode API Key est recommandée pour sa simplicité et sa fiabilité.
Q2：Quels formats de fichiers l'API de compression prend-elle en charge ?
L'API de la version serveur de SmartSlim prend en charge les formats PDF, images (jpg/jpeg/tif) et OFD, avec une limite de 1 Go par fichier. L'API de la version réseau de SmartSlim prend en charge les 10 catégories et plus de 40 formats (dont vidéo, audio, documents Office, etc.), avec une limite de 10 Go par fichier. Lors de l'appel, le paramètre format permet de spécifier le type de fichier ; s'il n'est pas transmis, la détection est automatique. Attention : la version serveur ne prend en charge que les trois formats PDF/images/OFD, le support de tous les formats nécessite la version réseau.
Q3：L'API de compression a-t-elle une limite de fréquence d'appel ?
Une stratégie de limitation de débit protège la stabilité du service. Limites par défaut : 60 requêtes par minute, 10 concurrents par seconde. En cas de dépassement, le code d'état 429 est renvoyé, les en-têtes de réponse contiennent les champs X-RateLimit-Remaining et X-RateLimit-Reset. La version entreprise peut passer à 300 requêtes par minute et 30 concurrents par seconde. Il est recommandé que le client implémente un mécanisme de reprise avec backoff exponentiel : après réception d'un 429, attendre 1-2-4 secondes en augmentant progressivement.
Q4：Comment l'API de compression gère-t-elle les gros fichiers ?
Pour les gros fichiers (plus de 50 Mo), l'interface de téléchargement par blocs est recommandée : le fichier est divisé en plusieurs blocs de 5 Mo, une fois le téléchargement terminé, la fusion et la compression sont notifiées. Une fois la compression terminée, le résultat est obtenu via notification de callback ou interrogation de l'interface de statut. La compression des gros fichiers est asynchrone et ne bloque pas l'appel API. La compression d'un PDF de 100 Mo prend environ 8 secondes, celle d'une vidéo de 1 Go environ 90 secondes, un lien de téléchargement étant généré automatiquement à la fin.
Conclusion
L'API RESTful de SmartSlim Server fournit 4 interfaces principales — compression par upload, compression par lot, interrogation de statut, notification par callback — couvrant tous les scénarios, du fichier unique au traitement par lot. Double choix d'authentification : API Key pour le côté serveur, Bearer Token pour le côté front-end. Stratégie de limitation de débit claire : 60 requêtes par minute par défaut, 300 pour la version entreprise, code d'état 429 avec reprise par backoff exponentiel. Un PDF numérisé de 80 Mo est compressé à 8,2 Mo en seulement 6,5 secondes, soit un taux de compression de 89,8 %.
Retenez trois points : premièrement, pour les fichiers de moins de 50 Mo, le résultat est renvoyé de manière synchrone ; au-delà, le traitement est asynchrone avec interrogation par identifiant de tâche ; deuxièmement, en cas de 429 de limitation de débit, implémentez un backoff exponentiel, ne relancez pas aveuglément ; troisièmement, pour les gros fichiers, utilisez l'interface de téléchargement par blocs, en blocs de 5 Mo. En choisissant la bonne interface et les bons paramètres, l'appel à l'API de compression est en réalité très simple. Si vous préférez l'intégration SDK locale aux appels HTTP, consultez le guide d'intégration du SDK de compression.
Articles connexes
Besoin de compresser des fichiers ? Essayez SmartSlim
Construit sur un moteur de compression Rust auto-développé, prenant en charge 10 catégories et plus de 40 formats, dont PDF, images, vidéo, Office et OFD, avec une compression locale qui garde vos données sur place.