Documentation de l’API

Formats et limites

L’API accepte les images statiques JPEG, PNG et WebP. Elle renvoie le format d’origine, JPEG, PNG ou WebP. GIF, BMP, HEIC, AVIF, JPEG XL, SVG, TIFF et les images animées ne sont pas pris en charge. La limite par fichier est de 5 Mo et 20 mégapixels. Le service vérifie le type MIME, la signature et le décodage ; ce contrôle ne remplace pas une analyse antivirus.

Clé d’accès

Créez une clé dans votre compte. Sa valeur complète n’est affichée qu’une fois. Transmettez-la dans l’en-tête Authorization et conservez-la sur votre serveur, jamais dans du code public.

Requête de compression

Envoyez une requête POST multipart/form-data à /api-compress.php. Le fichier est transmis dans image. Le paramètre facultatif format accepte original, jpeg, png ou webp ; original est utilisé par défaut. billing_mode accepte standard ou bitrix ; standard est utilisé par défaut. Une réponse réussie contient l’image traitée et les tailles dans les en-têtes.

curl

curl -X POST 'https://ankpicpress.com/api-compress.php' \
+  -H 'Authorization: Bearer ank_test_DEMO_ONLY_NOT_A_REAL_KEY' \
+  -F 'image=@photo.jpg' -F 'format=webp' --output photo.webp

Mode du module Bitrix

ank.imagecompress utilise billing_mode=bitrix et l’en-tête X-ANK-Request-ID composé de 64 caractères hexadécimaux. Réutilisez le même identifiant pour reprendre la même tâche. Un identifiant appliqué à un autre fichier ou format renvoie 409. Le résultat d’une reprise est conservé jusqu’à 30 jours. Dans ce mode, un crédit est débité uniquement si le résultat valide est plus petit que l’original. En mode standard, chaque traitement réussi coûte un crédit.

Disponibilité

GET /api-health.php ne nécessite pas de clé, ne traite pas d’image et ne consomme pas de crédit. Il renvoie 200 avec {"status":"ok"} si le service est disponible, ou 503 avec {"status":"unavailable"} si le contrôle échoue. HEAD renvoie le même statut sans corps.

Solde

GET /api-balance.php nécessite Authorization: Bearer <API_KEY>. La réponse contient free_remaining, paid_credits et total_available sans modifier le solde. Une clé invalide ou révoquée renvoie 401. La limite est de 60 requêtes par minute et par clé ; son dépassement renvoie 429.

Crédits et erreurs

Les 500 premières unités API de chaque mois civil sont gratuites et ne sont pas reportées. Chaque optimisation ou conversion réussie coûte un crédit. Les crédits achetés n’expirent pas. Erreurs : 400 requête invalide ; 401 clé invalide ; 402 solde insuffisant ; 413 taille excessive ; 415 format non pris en charge ; 429 limite de requêtes ; 503 erreur temporaire. Les erreurs sont renvoyées au format JSON dans le champ error.