L'endpoint POST /api/v1/convert accepte des fichiers ou des URLs et renvoie un job de conversion. Cette page décrit le flux complet : soumettre une conversion, attendre le résultat et récupérer les fichiers.

Base URL et documentation

Toutes les requêtes partent de https://pixshrink.app/api/v1. La documentation OpenAPI interactive est disponible sur /api/v1/docs. Le guide intégré avec des exemples détaillés est sur /compte/api/guide/ (Pro Plus requis).

Soumettre une conversion

Avec des fichiers (multipart)

curl -X POST https://pixshrink.app/api/v1/convert \
  -H "Authorization: Bearer px_live_a1b2c3d4.xxxxx..." \
  -F "files=@photo.jpg" \
  -F "files=@banniere.png" \
  -F "target_format=webp" \
  -F "quality=80"

Avec des URLs (JSON)

curl -X POST https://pixshrink.app/api/v1/convert \
  -H "Authorization: Bearer px_live_a1b2c3d4.xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://exemple.com/photo.jpg"],
    "target_format": "webp",
    "quality": 80
  }'

Paramètres de conversion

Paramètre	Obligatoire	Valeurs	Description
`files`	Au moins un des deux	Fichiers multipart	Fichiers images à convertir
`urls`	Au moins un des deux	Liste d'URLs HTTPS publiques	URLs d'images à fetcher et convertir (max 2048 chars chacune)
`target_format`	Non (défaut : `webp`)	`webp`, `jpeg`, `png`, `avif`	Format de sortie souhaité
`quality`	Non (défaut : `80`)	Entier 1–100	Qualité de compression
`max_width`	Non	Entier 64–8000	Largeur maximale en pixels — redimensionne si la source est plus large

Tu peux mélanger fichiers et URLs dans la même requête. Le total ne doit pas dépasser 100 images par requête.

Mode asynchrone (par défaut) et synchrone

Par défaut, POST /convert répond 202 Accepted immédiatement avec un objet job dont le status est pending. La conversion est traitée en arrière-plan.

En ajoutant ?sync=true, la requête attend jusqu'à 60 secondes que la conversion soit terminée et répond 200 OK avec le job complété (ou le job dans son état courant si le délai est dépassé).

POST https://pixshrink.app/api/v1/convert?sync=true

Structure d'un objet job

La réponse JSON contient un objet job avec les champs suivants :

Champ	Type	Description
`id`	UUID	Identifiant unique du job
`status`	string	`pending`, `processing`, `completed` ou `failed`
`target_format`	string	Format de sortie
`quality`	integer	Qualité utilisée
`images_count`	integer	Nombre d'images dans le job
`gain_percent`	float	Gain de compression moyen en %
`files_available`	boolean	`false` si les fichiers ont été purgés (après 14 jours)
`expires_at`	datetime	Date d'expiration des fichiers (14 jours après création)
`zip_url`	URL ou null	URL signée pour télécharger le ZIP (null si moins de 2 images)
`images`	liste	Détail de chaque image avec `download_url`, dimensions, poids, statut

Attendre la fin d'un job

Long-poll

GET https://pixshrink.app/api/v1/jobs/{uuid}/wait
Authorization: Bearer px_live_a1b2c3d4.xxxxx...

La requête attend jusqu'à 60 secondes que le job passe à completed ou failed. Si le délai est dépassé, elle répond avec le statut courant du job. Tu peux ajouter ?timeout=N pour ajuster (maximum 60).

Via webhook

Si tu as configuré un endpoint webhook, PixShrink t'envoie un événement job.completed ou job.failed dès que la conversion est terminée — sans avoir à interroger le serveur. Voir Configurer des webhooks.

Consulter et télécharger les résultats

Détails d'un job

GET https://pixshrink.app/api/v1/jobs/{uuid}
Authorization: Bearer px_live_a1b2c3d4.xxxxx...

Télécharger une image

Chaque image dans images[] contient un champ download_url. C'est une URL signée HMAC valable 14 jours — elle ne nécessite pas de header Authorization et peut être utilisée directement dans un navigateur ou un script.

Télécharger le ZIP

Si le job contient 2 images converties ou plus, le champ zip_url contient une URL signée vers le ZIP. Si le job n'a qu'une seule image, zip_url vaut null.

Supprimer un job

DELETE https://pixshrink.app/api/v1/jobs/{uuid}
Authorization: Bearer px_live_a1b2c3d4.xxxxx...

Supprime le job et tous ses fichiers disque immédiatement.

Limites et quotas

Limite	Valeur	Erreur si dépassé
Images par requête	100 (fichiers + URLs cumulés)	400 — Trop d'images : N > 100 max par requête.
Requêtes par heure (par clé)	600	429 — `rate_limited`
Rétention des fichiers	14 jours	404 — Fichiers expirés (rétention 14j).
Taille max par fichier	Illimitée pour Pro Plus	—
Long-poll timeout	60 secondes	Réponse avec statut courant

Erreurs courantes

Code HTTP	Code erreur	Cause	Solution
400	`bad_request`	Ni `files` ni `urls` fourni	Inclure au moins un fichier ou une URL
400	`ssrf_blocked`	URL pointant vers une IP interne ou loopback	Utiliser une URL vers un serveur public
403	`format_not_allowed`	Format non autorisé pour le tier	Utiliser `webp`, `jpeg` ou `png` si non Pro Plus
403	`missing_signature`	URL de téléchargement signée modifiée ou incomplète	Utiliser l'URL exacte renvoyée dans `download_url`
403	`invalid_signature`	Signature HMAC invalide ou URL expirée	Récupérer une nouvelle URL via `GET /jobs/{uuid}`
404	`files_expired`	Job de plus de 14 jours, fichiers purgés	Relancer une nouvelle conversion
404	`not_available`	Image non terminée (status `failed` ou `pending`)	Vérifier le status de l'image individuelle dans le job
429	`rate_limited`	Plus de 600 requêtes dans la dernière heure	Espacer les requêtes ou réduire la fréquence d'appel

Questions fréquentes

Mon job reste en status=pending, que faire ?

Un job en pending est en attente de traitement. Si l'état ne change pas après plusieurs minutes, cela peut indiquer un problème temporaire côté serveur. Contacte le support en indiquant l'UUID de ton job.

Le mode ?sync=true s'arrête avant la fin de la conversion

Le long-poll a un timeout de 60 secondes. Si la conversion dépasse ce délai (batch très large), la réponse sera retournée avec le statut courant. Récupère le résultat final via GET /jobs/{uuid} ou configure un webhook job.completed.

Puis-je lister mes jobs passés ?

Oui, via GET /api/v1/jobs (pagination par curseur). Voir la documentation sur /api/v1/docs.

Voir aussi : Créer une clé API · Configurer des webhooks · Utiliser le SDK Python