Comment ajouter des filtres photo pour adultes à votre application

Ajouter un filtre photo pour adultes à un produit ressemble à un problème d'image et se révèle être un problème de tuyauterie. Le travail du modèle s'achète en un seul appel via une API. Ce qui dévore le sprint, c'est tout ce qui l'entoure : des uploads qui expirent, des jobs qui se terminent quand personne n'écoute, des retries qui vous facturent deux fois en silence, et un support qui demande où est passé un résultat. Ce guide déroule l'intégration de bout en bout et pointe les endroits où l'on perd du temps de façon prévisible.

Ce que contient réellement l'intégration

Une API de transformation d'images est asynchrone par nature. La génération dure assez longtemps pour qu'il soit déraisonnable de maintenir une connexion HTTP ouverte : les réseaux mobiles coupent, les load balancers ferment les connexions inactives, et vos propres timeouts finissent par se retourner contre vous. La forme est donc toujours la même : vous soumettez un travail, vous recevez un identifiant, vous récupérez le résultat plus tard.

1. Envoyez la photo et le preset souhaité, et récupérez un identifiant de job.
2. Suivez le job, soit par polling, soit en vous abonnant aux événements.
3. Récupérez l'image terminée lorsque le job passe en succès.
4. Gérez les chemins d'échec et de retry, là où se trouve l'essentiel du vrai travail.

Étape 1 : soumettre le job

La soumission est une requête multipart qui transporte l'image, l'identifiant du preset et la confirmation que vous disposez des droits et du consentement nécessaires au traitement de la photo. Joignez-y une clé d'idempotence. Cet unique en-tête fait la différence entre une intégration propre et un incident support, et il ne coûte rien à ajouter.

curl -X POST https://api.example/api/v1/jobs \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@photo.jpg \
  -F feature=bikini \
  -F consent=confirmed

La réponse contient l'identifiant du job et son statut initial. Persistez cet identifiant sur votre propre enregistrement utilisateur ou session immédiatement, avant toute autre chose. Si votre process meurt la seconde suivante, cette ligne en base est la seule chose qui vous permettra de retrouver le travail.

Étape 2 : suivre l'avancement

Il existe deux façons de suivre un job, et les intégrations matures utilisent les deux. Une connexion WebSocket vous donne les changements de statut et la progression en direct, ce qu'il faut pour piloter une barre de progression dans l'interface. Le polling de l'endpoint du job est le repli qui rend le système correct et pas seulement agréable : les sockets tombent, les téléphones se mettent en veille, et un poll toutes les quelques secondes ne coûte presque rien.

Traitez le WebSocket comme une optimisation et le polling comme la source de vérité. Les équipes qui inversent cet ordre se retrouvent avec des jobs parfaitement terminés côté serveur et bloqués pour toujours côté client, parce que le seul événement qui comptait est arrivé pendant que la socket se reconnectait.

Étape 3 : récupérer le résultat

Quand le job passe en succès, il contient une liste de sorties. Chaque sortie se récupère avec la même clé d'API que celle qui a créé le job : les résultats ne sont donc jamais adressables publiquement ni devinables à partir d'une URL. Téléchargez l'image dans votre propre stockage dès réception si votre produit doit l'afficher plus tard — une API d'images est un service de traitement, pas une photothèque, et les résultats ne sont pas conservés indéfiniment.

Étape 4 : échecs, retries et le piège de la double facturation

L'échec intéressant n'est pas celui où l'API renvoie une erreur. C'est le cas ambigu : votre requête est partie, le réseau a coupé, et vous ignorez si le job a été créé. Réessayez naïvement et vous aurez payé deux fois et produit deux résultats pour une seule action utilisateur.

C'est exactement ce que résout la clé d'idempotence. Répétez la requête avec la même clé et vous récupérez le job d'origine plutôt qu'un nouveau, quel que soit le nombre de retries. Générez la clé au moment de l'action utilisateur, stockez-la avec l'enregistrement du job, et réutilisez-la pour chaque nouvelle tentative de cette même action — pas une clé neuve par tentative, ce qui annulerait tout le mécanisme.

Là où les intégrations s'enlisent

• Valider les uploads uniquement côté client. Vérifiez le fichier côté serveur d'après son contenu, pas son extension, avant de dépenser un appel d'API.
• Construire tout le flux en synchrone, puis découvrir que les clients mobiles coupent la connexion bien avant la fin de la génération.
• Considérer le WebSocket comme unique canal de progression, sans repli par polling.
• Ne rien stocker localement, si bien qu'un redémarrage perd la correspondance entre vos utilisateurs et les jobs en cours.
• Oublier que les résultats sont éphémères et attendre de l'API qu'elle serve de stockage permanent.

Un ordre de travail raisonnable

Faites passer une photo par tout le parcours avec curl avant d'écrire la moindre ligne de code applicatif : soumission, polling, téléchargement. Câblez ensuite ces mêmes quatre appels dans votre backend, avec persistance. Ajoutez le WebSocket en dernier, purement comme amélioration de la barre de progression, par-dessus un système qui fonctionne déjà sans lui. Dans cet ordre, l'intégration prend une journée ; dans l'ordre inverse, c'est deux semaines de débogage.

Questions fréquentes