Le SDK Python PixShrink enveloppe l'API REST dans une interface Python simple. Il couvre toutes les opérations : conversion, gestion des jobs, téléchargement, clés API et webhooks. Cette page explique comment l'installer et l'utiliser.

Installation

Le SDK n'est pas encore disponible sur PyPI. Si tu as accès au code source, installe-le depuis le répertoire sdk/ du dépôt :

pip install -e ./sdk

Prérequis :

Python 3.9 ou supérieur
La bibliothèque requests (installée automatiquement)

Créer un client

from pixshrink import Client

c = Client("px_live_a1b2c3d4.xxxxx...")

Passe ta clé API Pro Plus en argument. La clé est utilisée pour toutes les requêtes suivantes. Voir Créer une clé API si tu n'en as pas encore.

Vérifier son compte et son quota

# Infos du compte
me = c.me()
# {"email": "...", "tier": "pro_plus", "is_internal_key": false}

# Quota et statistiques
usage = c.usage()
# {"weekly_count": 12, "weekly_limit": null, "weekly_remaining": null, ...}

# Formats disponibles pour ton tier
formats = c.formats()

Convertir des images

# Conversion depuis des fichiers locaux
job = c.convert(
    files=["photo.jpg", "banniere.png"],
    target_format="webp",
    quality=80,
    max_width=1920,   # optionnel — redimensionne si plus large
    sync=False        # async par défaut (202)
)
print(job["id"], job["status"])  # ex: "abc123...", "pending"

# Conversion depuis des URLs
job = c.convert(
    urls=["https://exemple.com/photo.jpg"],
    target_format="avif",
    quality=70
)

Les paramètres target_format, quality et max_width sont les mêmes que pour l'API REST. Le batch max est de 100 images par appel (fichiers + URLs cumulés).

Attendre la fin d'un job

# Long-poll : attend jusqu'à 60 secondes (configurable)
job = c.wait(job["id"], timeout=60)
print(job["status"])  # "completed" ou "failed"

Télécharger les résultats

for img in job["images"]:
    if img["status"] == "completed":
        # download_url est une URL signée, valable 14 jours
        c.download(img["download_url"], dest="./output/")

# Télécharger le ZIP (si 2+ images)
if job["zip_url"]:
    c.download(job["zip_url"], dest="./output/")

La méthode download(url, dest) enregistre le fichier dans le répertoire dest sous son nom d'origine.

Exemple minimal complet

from pixshrink import Client

c = Client("px_live_a1b2c3d4.xxxxx...")

# Lancer la conversion
job = c.convert(files=["photo.jpg"], target_format="webp")

# Attendre le résultat
job = c.wait(job["id"])

# Télécharger
for img in job["images"]:
    if img["status"] == "completed":
        c.download(img["download_url"], dest="./output/")
        print(f"Téléchargé : {img['output_filename']}")

Gérer les jobs

# Lister les jobs (paginé par curseur)
jobs = c.jobs()

# Détails d'un job
job = c.job("550e8400-...")

# Supprimer un job et ses fichiers
c.delete_job("550e8400-...")

Gérer les clés API

# Lister les clés
keys = c.list_keys()

# Créer une clé (renvoie la clé en clair une seule fois)
result = c.create_key(name="Mon script")
print(result["full_key"])  # À copier immédiatement

# Révoquer une clé
c.revoke_key(key_id="...")

Gérer les webhooks

# Lister les endpoints
webhooks = c.list_webhooks()

# Créer un endpoint (renvoie le secret une seule fois)
wh = c.create_webhook(
    url="https://ton-serveur.com/webhook",
    events=["job.completed", "job.failed"],
    description="Mon endpoint de prod"
)
print(wh["secret"])  # À copier immédiatement

# Supprimer un endpoint
c.delete_webhook(webhook_id="...")

Gérer les erreurs

Toutes les erreurs API lèvent des exceptions héritées de APIError :

Exception	Déclenchée par
`AuthenticationError`	401 — clé absente, invalide ou révoquée
`PermissionError`	403 — tier insuffisant ou droits manquants
`ValidationError`	400 — payload invalide (format inconnu, batch trop grand…)
`QuotaExceeded`	429 avec code `quota_exceeded` — limite hebdomadaire dépassée
`RateLimited`	429 autre — trop de requêtes dans l'heure
`ServerError`	5xx — erreur côté serveur PixShrink
`APIError` (base)	Toute autre erreur HTTP de l'API

from pixshrink import Client
from pixshrink.exceptions import QuotaExceeded, RateLimited, AuthenticationError

c = Client("px_live_a1b2c3d4.xxxxx...")

try:
    job = c.convert(files=["photo.jpg"], target_format="webp")
except AuthenticationError:
    print("Clé API invalide ou révoquée")
except QuotaExceeded:
    print("Quota hebdomadaire dépassé")
except RateLimited:
    print("Trop de requêtes, réessaie dans un moment")

Questions fréquentes

Le SDK est-il disponible sur PyPI ?

Le SDK est actuellement en version Beta. Sa disponibilité sur PyPI n'est pas encore confirmée — consulte la documentation sur /api/v1/docs pour les informations les plus récentes.

Le SDK supporte-t-il Python 2 ?

Non. Le SDK requiert Python 3.9 minimum.

Puis-je utiliser le SDK sans clé API ?

Non. Toutes les méthodes du SDK nécessitent une clé API Pro Plus valide. Sans clé, chaque appel lèvera une AuthenticationError.

Voir aussi : Convertir des images via l'API · Créer une clé API