Documentation API et MCP

L’accès API gratuit est une fonction cloud distincte de l’outil navigateur. Après connexion avec un compte @gmail.com vérifié par Google et validation Turnstile, il fournit 500 credits par mois UTC sans carte bancaire, sous réserve d’un budget mensuel de calcul gratuit de $20.

Créez une clé API dans les paramètres du compte après activation. Toutes les clés du compte partagent le même pool de credits, les mêmes limites de débit et les mêmes plafonds de tâches inachevées. Lorsque le budget de calcul gratuit est épuisé, les nouvelles tâches gratuites sont mises en pause jusqu’à l’heure de réinitialisation affichée ; les tâches Developer payantes et la compression locale dans le navigateur continuent séparément.

Envoyez une requête multipart avec un fichier GIF et un champ options contenant du JSON. Le mode cible utilise des octets décimaux dans targetBytes ; n’envoyez pas mode ou targetBytes comme champs de formulaire séparés.

Chaque requête de création doit inclure un Idempotency-Key au niveau du compte. Réutiliser la même clé avec le même fichier et les mêmes options renvoie la tâche d’origine sans réserver de credits à nouveau.

La réponse de création contient un id au niveau supérieur. Enregistrez-le comme JOB_ID et utilisez-le dans l’URL de statut ; il n’est pas imbriqué dans une propriété job. La réponse de création seule ne contient pas de lien de téléchargement. Interrogez le point de statut même lorsque la création rejoue une tâche déjà terminée. Remplacez YOUR_JOB_ID dans l’exemple par cet id, puis copiez result.downloadUrl depuis une réponse succeeded dans DOWNLOAD_URL avant d’exécuter la commande de téléchargement.

Tant que le statut est queued ou processing, result vaut null. Quand le statut est succeeded, lisez result.downloadUrl et result.expiresInSeconds. En cas de failed ou canceled, arrêtez l’interrogation et inspectez error.code et error.message au lieu de tenter un téléchargement.

Interrogez toutes les quelques secondes et restez dans la limite de lecture du compte. Une nouvelle requête de statut peut rafraîchir un lien expiré tant que le fichier reste accessible. Les liens durent jusqu’à 15 minutes et ne prolongent jamais l’accès au fichier au-delà de 24 heures. L’interrogation, le téléchargement et la répétition idempotente exacte ne dépensent pas de credits.

Les requêtes JSON de création utilisent sourceUrl et options. Le serveur récupère uniquement des URL HTTPS, valide chaque redirection, bloque les réseaux privés et applique les mêmes limites de taille que pour les téléversements.

Si un site bloque le CORS du navigateur, l’import d’URL local peut échouer. L’import d’URL REST reste une tâche cloud et utilise votre clé API, vos credits, vos limites de débit et les règles de conservation.

GET /api/v1/usage renvoie { usage }. L’objet usage inclut le pool actif, limit, used, reserved, remaining, resetAt, windowStart et windowEnd. Les requêtes de création Free sont limitées à 10 rpm, les requêtes de création Developer à 60 rpm, et les lectures de statut ou d’usage à 120 rpm par compte.

Les fenêtres Free API se réinitialisent par mois calendaire UTC. Les fenêtres Developer se réinitialisent chaque mois à l’ancre de l’abonnement, y compris pour les abonnements annuels. Les credits ne sont pas reportés. Les comptes Free peuvent avoir 2 tâches inachevées, les comptes Developer 20, et la file gratuite peut contenir 100 tâches. Une tâche gratuite qui attend plus de 10 minutes est terminée et libère sa réservation.

Le point de terminaison MCP est Streamable HTTP sur /api/mcp. Il expose compress_gif, get_compression et get_usage, et utilise la même clé API que REST.

MCP accepte des URL GIF HTTPS distantes. Les fichiers locaux doivent être téléversés via REST ; ne transmettez pas de chemins locaux serveur ni de gros payloads Base64 à l’outil MCP.

Appelez compress_gif avec sourceUrl, un objet options facultatif et un idempotencyKey obligatoire. Passez ensuite l’id retourné à get_compression. L’adaptateur enveloppe la réponse REST dans structuredContent.data ; un transport d’outil réussi ne signifie pas que la tâche de compression est terminée. Utilisez get_usage avec un objet vide pour vérifier votre solde.

Les entrées jusqu’à 5MB coûtent 1 credit en mode qualité ou taille et 2 credits en mode cible. Les entrées de plus de 5MB et jusqu’à 20MB coûtent 2 credits, ou 4 credits en mode cible. Chaque tentative de traitement dispose d’un budget de 60 secondes et d’au plus 8 candidats encodés.

Les échecs de validation, les échecs système et les timeouts ne dépensent pas les credits utilisateur. Un résultat valide qui manque la cible demandée dépense quand même le devis annoncé, car le calcul a été effectué ; la tâche marque targetMet: false.

Les champs credits et cost.credits de la tâche indiquent le coût annoncé, pas la preuve d’un débit terminé. Les credits sont réservés lorsqu’une tâche est acceptée, réglés en cas de succès et libérés en cas d’échec. Consultez /api/v1/usage pour connaître les soldes actuels used, reserved et remaining.

Les codes d’erreur courants incluent API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS et FREE_COMPUTE_BUDGET_EXHAUSTED.

401 couvre les clés API manquantes ou invalides. 402 concerne uniquement les credits utilisateur épuisés. 403 couvre un accès Free API inactif. 409 couvre les conflits d’idempotence. 413 couvre les limites de taille d’entrée cloud. 422 couvre les données GIF ou options invalides. 429 couvre les limites de débit création/lecture et les plafonds de tâches inachevées. 503 couvre une pression temporaire sur la file ou FREE_COMPUTE_BUDGET_EXHAUSTED ; respectez Retry-After lorsqu’il est présent.

La compression locale dans le navigateur et les tâches API cloud ont des flux de données différents. Choisissez l’outil navigateur lorsque le GIF doit rester sur votre appareil ; utilisez REST ou MCP lorsqu’un workflow distant doit le traiter.

L’outil navigateur n’envoie pas votre GIF à nos serveurs. L’import par URL contacte directement le site qui héberge l’image. Avec l’API et MCP, vous envoyez un fichier ou demandez au service de récupérer une URL HTTPS publique. Cloudflare héberge l’application, la base de données et les fichiers. L’accès aux fichiers API d’entrée et de sortie expire après 24 heures ; les liens de téléchargement durent au maximum 15 minutes. Les fichiers expirés sont supprimés en arrière-plan, la suppression effective peut donc intervenir plus tard. Pour suivre la fiabilité et l’utilisation, nous enregistrons dans les journaux Cloudflare des événements techniques : succès ou échec de compression, tailles d’entrée et de sortie, cible atteinte ou non, téléchargements. Ils ne contiennent ni noms de fichiers, ni URL sources, ni contenu des fichiers. Cloudflare traite aussi les données de requête nécessaires au fonctionnement et à la sécurité du service. Les journaux d’événements produit sont conservés au maximum 7 jours.

Envoyez Authorization: Bearer YOUR_API_KEY sur les requêtes de création, de statut et d’usage. L’API accepte aussi l’en-tête x-api-key. Les cookies de connexion au compte ne remplacent pas une clé API. Toutes les clés d’un même compte partagent les quotas et limites.

Gardez la clé dans une variable d’environnement côté serveur ou dans la configuration protégée de votre client IA. Ne la placez pas dans une page web publique, un dépôt ou une URL d’image. Si une clé est exposée, révoquez-la dans les paramètres de clés API et créez un remplacement. L’outil navigateur gratuit n’a pas besoin de clé API.

mode accepte quality, size ou target et vaut quality par défaut. target exige un entier positif targetBytes, mesuré en octets décimaux : 100KB vaut 100000 et 1MB vaut 1000000. Pour les téléversements multipart, placez ces champs dans le champ options encodé en JSON.

colors accepte facultativement auto, 64, 128 ou 256. lossyLevel accepte un entier de 0 à 200. width accepte un entier de 1 à 4096 et demande un redimensionnement ; omettez-le pour conserver les dimensions d’origine. Aucune option de suppression d’images ni de conversion de format n’est prise en charge.

Une requête traite un GIF. Les entrées Free API sont limitées à 5MB et les entrées Developer à 20MB. Dans les deux cas, chaque côté doit aussi mesurer au plus 4096 pixels, il doit y avoir au plus 1 000 images, et largeur × hauteur × nombre d’images doit être au plus 50 000 000. Une animation courte mais très grande peut atteindre ces limites de sécurité avant sa limite en octets.

Choisissez un nouvel Idempotency-Key pour chaque nouvelle requête fichier-et-options, puis conservez cette clé lorsque vous réessayez après une réponse réseau incertaine. Les clés contiennent 1 à 128 caractères ASCII imprimables sans espace. Une répétition identique renvoie la tâche existante ; changer l’entrée ou les options sous la même clé renvoie 409 IDEMPOTENCY_CONFLICT.

Pour les réponses 429 ou les 503 temporaires, respectez Retry-After lorsqu’il est présent et augmentez l’attente. Un manque de credits 402 nécessite une réinitialisation de quota ou un changement de formule ; répéter les requêtes ne le corrige pas. Un 503 FREE_COMPUTE_BUDGET_EXHAUSTED met en pause les nouvelles tâches gratuites jusqu’à la réinitialisation affichée, tandis que les tâches payantes et l’outil navigateur local restent séparés.

Si une tâche échoue, lisez error.code avant de recommencer. Réessayer après INVALID_GIF nécessite généralement un autre fichier ; réessayer après INPUT_TOO_LARGE nécessite une entrée plus petite ou une autre formule. Lancez une nouvelle tentative volontaire avec un nouvel Idempotency-Key, mais gardez la même clé pour les vrais retries réseau.