Intégrer une API d’images IA dans le pipeline d’une agence : clés, registre et archives

La référence de l’API explique comment créer une image. Une agence a un autre problème : des milliers d’images, une douzaine de clients, trois personnes qui appuient sur des boutons et une personne aux finances qui demande à la fin du mois qui a utilisé quoi. Rien de tout cela n’est difficile, mais chaque partie est facile à rater la première semaine. Voici six règles, chacune tirée du comportement réel de l’API et non de ce que nous aimerions qu’elle fasse. Si vous n’avez pas encore envoyé de première requête, commencez par l’introduction à l’API.

Règle 1 : une clé par client, un seul portefeuille derrière

Les clés se créent dans l’API Console, chacune avec un nom, et la clé complète n’est affichée qu’une seule fois. Nommez-les d’après vos clients. Une clé qui a fuité, ou un contrat qui prend fin, se révoque individuellement et les autres continuent de fonctionner. Ce que les clés ne font pas, c’est séparer l’argent : toutes les clés du compte puisent dans le même solde de coins. Si deux clients ne doivent jamais partager un solde, il faut deux comptes, et les coins ne peuvent pas être transférés d’un compte à l’autre par la suite.

Règle 2 : votre registre, indexé par votre identifiant de tâche

L’endpoint de liste renvoie tout le compte, images du studio comprises, et non le travail d’une seule clé. Tenez donc votre propre registre : client, tâche, identifiant de génération, coins débités. La façon la plus propre de les relier est l’en-tête Idempotency-Key. Construisez-le à partir de votre propre identifiant de tâche, et une requête relancée après une connexion perdue renverra la génération qui existe déjà au lieu d’en facturer une seconde. Donnez-lui un préfixe propre à votre agence, une chaîne aléatoire suffit, car la clé est vérifiée sur l’ensemble du service, pas seulement sur votre compte.

POST /v1/api/images
Authorization: Bearer fk_live_key_for_client_a
Idempotency-Key: 7f1c2b90-client-a-deck-0042

{
  "prompt": "a linen shirt on a wooden hanger, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

La réponse est un 202 avec l’identifiant de la génération et coinsCharged ; inscrivez les deux dans le registre avant toute autre chose.

Règle 3 : interrogez, n’attendez pas

Une génération est mise en file d’attente et s’exécute en arrière-plan. Interrogez son statut à intervalle raisonnable (la réponse contient une estimation dans etaMs tant qu’elle est en file) et lancez plusieurs tâches à la fois plutôt que l’une après l’autre : l’API autorise plus de tâches parallèles par compte que le studio, parce que c’est son usage normal.

GET /v1/api/images/{id}          -> "queued", "generating", then "succeeded",
                                    or "failed" / "refunded" with refunded: true
GET /v1/api/images/{id}/content  -> the bytes, until the retention window ends
                                    (after that: 410 BYTES_EXPIRED)

Règle 4 : traitez l’échec comme une donnée

Une génération échouée rembourse automatiquement ses coins et l’indique dans refunded. Son failureCode fait partie d’une courte liste fixe : TIMEOUT et VENDOR_ERROR méritent une nouvelle tentative plus tard, MODERATION_REJECTED signifie que le prompt doit être réécrit plutôt que répété, et UNKNOWN couvre le reste. Notez le code dans votre registre ; un client dont le brief déclenche sans cesse la modération appelle une conversation, pas une boucle de tentatives. L’économie des nouvelles tentatives est détaillée dans l’article sur les tarifs et les échecs.

Règle 5 : archivez dès que c’est réussi

L’API n’est pas une photothèque. Les fichiers terminés sont supprimés à la fin de la durée de conservation indiquée sur la page produit, et ensuite la requête de contenu répond 410 BYTES_EXPIRED. Téléchargez chaque image réussie dans votre propre stockage immédiatement, sous le client et la tâche de votre registre, et si un client ne veut pas du tout que nous conservions ses images, supprimez-les via l’API une fois archivées.

Règle 6 : vérifiez les limites dans le code, et placez un humain avant la livraison

Chaque clé a un débit de requêtes, et le compte a un quota quotidien d’images. Les deux sont renvoyés par un seul appel, ce qui permet à un traitement par lot de vérifier avant de démarrer au lieu d’échouer à mi-chemin :

GET /v1/api/me
-> { "keyName": "client-a", "coins": ..., "rateLimitPerMin": ..., "dailyImagesRemaining": ... }

Les chiffres eux-mêmes figurent sur la page produit. Et avant que quoi que ce soit n’arrive chez un client, quelqu’un le regarde. Un modèle peut mettre six doigts à une main ou un mauvais mot sur une enseigne, et un pipeline automatisé livre cela aussi vite qu’une bonne image.

Ce que l’API ne fera pas pour une agence

Elle n’a ni sous-comptes, ni soldes par client, ni rapport d’utilisation par clé : cette comptabilité vous revient. Il n’y a ni accord de niveau de service ni délai de livraison garanti, alors ne promettez pas à un client des minutes que vous n’avez pas mesurées. Elle ne fait pas d’une image générée votre propriété au sens du droit d’auteur, comme l’explique à qui appartiennent les images IA, même si l’usage commercial est autorisé et que nous ne prenons aucune part. Et le visage d’une personne réelle exige toujours l’autorisation de cette personne, quel que soit le chemin de la requête.

Le budget en coins derrière tout cela est traité dans ce qu’une équipe dépense vraiment, et le studio pour les images faites à la main, c’est Fellowi Images.