Documentation

Présentation

Le service repose sur imagor et libvips. La compression utilise la quantification de palette pour les PNG et mozjpeg pour les JPEG — c'est la même approche que les services commerciaux de compression, exécutée ici sur un serveur que vous contrôlez.

L'API accepte un fichier envoyé en multipart/form-data et renvoie directement l'image traitée. Aucune URL source n'est acceptée : le service ne va jamais chercher une image sur le réseau à votre place.

Authentification

Chaque appel exige une clé d'API, créée depuis votre tableau de bord. Une clé ressemble à img_live_… et n'est affichée qu'une seule fois : elle n'est stockée qu'en empreinte, personne ne peut la retrouver ensuite, pas même un administrateur.

Deux en-têtes sont acceptés, au choix :

Authorization: Bearer img_live_VOTRE_CLE
X-API-Key: img_live_VOTRE_CLE

Créez autant de clés que de machines ou de scripts : chacune se révoque indépendamment, et le tableau de bord affiche la date de dernier usage de chacune.

Démarrage rapide

Exportez votre clé une fois pour toutes dans votre terminal :

export IMG_KEY="img_live_VOTRE_CLE"

Compresser sans rien changer d'autre

curl -X POST "https://imagor.creativecodegen.com/api/v1/compress" \
  -H "Authorization: Bearer $IMG_KEY" \
  -F "file=@photo.jpg" \
  -o photo.min.jpg

Vérifier que la clé fonctionne

curl "https://imagor.creativecodegen.com/api/v1/me" -H "Authorization: Bearer $IMG_KEY"

Endpoints

POST /api/v1/compress

Compresse en conservant le format d'origine, sauf si format est précisé. C'est l'endpoint à utiliser par défaut.

curl -X POST "https://imagor.creativecodegen.com/api/v1/compress?quality=80" \
  -H "Authorization: Bearer $IMG_KEY" \
  -F "file=@photo.jpg" -o out.jpg

POST /api/v1/resize

Redimensionne, et compresse au passage. Au moins width ou height est obligatoire. Préciser une seule des deux dimensions conserve les proportions.

curl -X POST "https://imagor.creativecodegen.com/api/v1/resize?width=1200&fit=contain" \
  -H "Authorization: Bearer $IMG_KEY" \
  -F "file=@photo.jpg" -o out.jpg

POST /api/v1/convert

Convertit vers un autre format. format est obligatoire ici. Passer en WebP ou AVIF reste le levier le plus efficace pour réduire le poids.

curl -X POST "https://imagor.creativecodegen.com/api/v1/convert?format=avif&quality=55" \
  -H "Authorization: Bearer $IMG_KEY" \
  -F "file=@photo.jpg" -o out.avif

GET /api/v1/me

Renvoie l'état du compte, le quota restant et la consommation des trente derniers jours. Aucun quota n'est décompté par cet appel.

Paramètres

Tous les paramètres se passent indifféremment dans la query string ou comme champs du formulaire multipart. Le fichier lui-même va dans le champ file.

Dimensions

Compression

Sortie

Formats

En entrée : JPEG, PNG, WebP, GIF, AVIF, HEIC, TIFF et JPEG XL. Le format réel est détecté à partir des octets du fichier, pas de son extension ni du type déclaré.

En sortie : JPEG, PNG, WebP, AVIF, JPEG XL, GIF et TIFF.

Le SVG est refusé, en entrée comme en sortie. Un SVG est un document exécutable, qui peut embarquer des scripts et des références réseau : le rendre côté serveur reviendrait à exécuter du contenu fourni par l'appelant.

Réponse et en-têtes

La réponse est l'image binaire. Les informations sur le traitement voyagent dans les en-têtes, ce qui évite d'avoir à décoder du JSON pour connaître le gain.

Un X-Saved-Bytes négatif signifie que le fichier a grossi : c'est normal quand on convertit une image déjà très compressée vers un format sans perte, ou quand la source était déjà optimisée au maximum.

curl -sS -X POST "https://imagor.creativecodegen.com/api/v1/compress" \
  -H "Authorization: Bearer $IMG_KEY" \
  -F "file=@photo.jpg" \
  -o /dev/null -D - | grep -i "^x-saved"

Erreurs

Toute erreur renvoie un JSON de la forme { "error": { "code": "...", "message": "..." } }.

Quotas et limites

Un quota horaire glissant s'applique par compte ; sa valeur exacte et le nombre d'appels restants figurent dans GET /api/v1/me et dans les en-têtes X-RateLimit-* de chaque réponse.

La taille maximale par fichier et le quota sont réglés par l'administrateur de l'instance. Les images sont plafonnées à 50 mégapixels et 20 000 pixels de côté. Rien n'est conservé : les fichiers sont traités en mémoire puis oubliés. Seules les métadonnées d'usage — taille, format, durée — sont journalisées.

Recettes

Une fonction shell réutilisable

imgmin() {
  curl -sS -X POST "https://imagor.creativecodegen.com/api/v1/compress" \
    -H "Authorization: Bearer $IMG_KEY" \
    -F "file=@$1" -o "${1%.*}.min.${1##*.}" -D /tmp/imgmin.h
  grep -i "^x-saved-percent" /tmp/imgmin.h
}

# usage : imgmin photo.jpg

Traiter un dossier entier

for f in *.jpg *.png; do
  [ -e "$f" ] || continue
  curl -sS -X POST "https://imagor.creativecodegen.com/api/v1/compress" \
    -H "Authorization: Bearer $IMG_KEY" \
    -F "file=@$f" -o "optimise/$f"
  echo "$f traité"
done

Générer les tailles d'un site responsive

for w in 400 800 1200 1600; do
  curl -sS -X POST "https://imagor.creativecodegen.com/api/v1/resize?width=${w}&format=webp&quality=80" \
    -H "Authorization: Bearer $IMG_KEY" \
    -F "file=@hero.jpg" -o "hero-${w}.webp"
done

Node.js

import { readFile, writeFile } from 'node:fs/promises'

const form = new FormData()
form.append('file', new Blob([await readFile('photo.jpg')]), 'photo.jpg')

const res = await fetch('https://imagor.creativecodegen.com/api/v1/compress?quality=80', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.IMG_KEY}` },
  body: form,
})

if (!res.ok) throw new Error((await res.json()).error.message)

console.log(`Gain : ${res.headers.get('x-saved-percent')} %`)
await writeFile('photo.min.jpg', Buffer.from(await res.arrayBuffer()))

Python

import os, requests

with open("photo.jpg", "rb") as f:
    res = requests.post(
        "https://imagor.creativecodegen.com/api/v1/compress",
        headers={"Authorization": f"Bearer {os.environ['IMG_KEY']}"},
        files={"file": f},
        params={"quality": 80},
    )

res.raise_for_status()
print("Gain :", res.headers["X-Saved-Percent"], "%")
open("photo.min.jpg", "wb").write(res.content)

Depuis Claude Code

Exportez la clé dans votre environnement, puis décrivez simplement ce que vous voulez : l'agent construira la commande curl lui-même.

export IMG_KEY="img_live_VOTRE_CLE"

Pour que l'agent connaisse l'API sans avoir à la redécouvrir, ajoutez ces quelques lignes au CLAUDE.md de vos projets :

## Compression d'images

Endpoint : POST https://imagor.creativecodegen.com/api/v1/compress
Auth     : header "Authorization: Bearer $IMG_KEY"
Fichier  : champ multipart "file"
Options  : quality, width, height, fit, format, max_bytes, palette

Exemple :
curl -X POST "https://imagor.creativecodegen.com/api/v1/compress?quality=80" \
  -H "Authorization: Bearer $IMG_KEY" -F "file=@image.jpg" -o image.min.jpg

Documentation complète : https://imagor.creativecodegen.com/doc