API GPT Image Edit sur TokenLab : endpoint correct et formats d'entrée d'image

L'édition d'images est l'un des aspects les plus exigeants de l'interface d'un produit d'IA : un utilisateur téléverse une photo, décrit une modification et attend un résultat. Les éditions qui utilisent plusieurs images sources, un canevas de grande taille ou un prompt plus lourd prennent plus de temps que ce qu'un appel HTTP synchrone classique ne permet confortablement. Ce guide détaille l'endpoint TokenLab correct, les deux formats d'entrée d'image pris en charge, les éditions multi-images et la voie asynchrone pour les requêtes lentes.

L'endpoint

L'édition d'images se trouve à l'adresse POST /v1/images/edits — notez le pluriel edits. (Une erreur courante consiste à écrire /images/edit, qui n'est pas le chemin documenté.)

L'endpoint prend en charge deux formats de requête :

• Un flux de téléversement multipart/form-data compatible avec OpenAI.
• Une requête JSON fournissant image_url, image_urls ou des références images[] officielles pour les familles image-to-image prises en charge.

L'ensemble des champs de requête et de réponse est documenté dans la référence de l'API d'édition d'image.

Ce que gpt-image-2 accepte ici

• Téléversements image en multipart.
• image_url ou image_urls en JSON.
• Références images[] officielles, où chaque objet contient exactement l'un des champs image_url ou file_id.
• Jusqu'à 16 images sources par requête.

Quelques contraintes à connaître avant d'écrire du code :

• Les éditions gpt-image-2 n'acceptent pas resolution ; utilisez size pour les dimensions de sortie (soit auto, soit WIDTHxHEIGHT, avec des dimensions multiples de 16, le bord le plus long ne dépassant pas 3840px, et un ratio bord long/bord court d'au plus 3:1).
• background accepte auto ou opaque ; transparent n'est pas pris en charge.
• input_fidelity ne fait pas partie des champs pris en charge pour gpt-image-2 ; l'envoyer renvoie 400 unsupported_parameter.
• Pour les requêtes JSON, fournissez exactement l'un des champs image_url, image_urls ou images. Chaque objet de images[] doit contenir exactement un champ parmi image_url ou file_id. Les valeurs de file_id doivent d'abord être créées via /v1/files.
• Les requêtes avec image de référence pour Nano Banana doivent être envoyées à /v1/images/generations avec operation: "image-to-image" et image_urls — pas à /v1/images/edits.

Téléversements multipart vs références d'image JSON

Les deux fonctionnent pour gpt-image-2. Choisissez celui qui correspond à l'emplacement où se trouvent déjà les octets de votre image.

Multipart — utilisez ceci lorsque l'application détient le fichier, qu'il provienne d'un téléversement utilisateur ou d'une ressource générée. Répétez le champ image pour envoyer plusieurs sources. Les fichiers doivent être au format PNG, JPEG ou WebP, et ne pas dépasser 50 MiB chacun.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

URL d'image JSON — utilisez ceci lorsque les images se trouvent déjà à une URL publique, ou que vous les avez générées lors d'une requête TokenLab précédente et disposez déjà d'une URL.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

Les URL distantes doivent être en http/https publiques, sans identifiants ni fragments intégrés, et ne doivent pas résoudre vers localhost ou des plages d'adresses IP privées ou réservées. TokenLab récupère les octets et les transmet au modèle sous forme de parties image en multipart. La limite par image est de 50 MiB ; la limite cumulée pour les images récupérées par URL dans une seule requête est de 200 MiB ; le délai d'expiration de récupération est de 30 secondes ; jusqu'à 3 redirections sont suivies.

Éditions multi-images et polling asynchrone

Les éditions multi-images représentent le cas d'usage le plus évident pour async: true. Envoyer plusieurs images avec un ensemble complexe d'instructions via un appel synchrone implique de maintenir une connexion ouverte pendant toute la durée nécessaire au modèle. Définissez async: true sur gpt-image-2 (et sur les modèles d'édition officiels FLUX/BFL) pour recevoir une tâche à la place :

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Interrogez l'adresse poll_url renvoyée, ou effectuez un appel de secours vers GET /v1/tasks/{task_id}. Les statuts sont pending, processing, completed et failed. Une tâche d'image terminée renvoie data[].url. Une vérification toutes les 3 à 5 secondes suffit ; arrêtez-vous dès qu'un statut terminal est atteint plutôt que de continuer à interroger.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Les tâches d'édition asynchrones renvoient les URL finales des images, quel que soit le response_format demandé. Si vous avez besoin de b64_json brut, utilisez une requête synchrone.

La facturation peut réserver le montant estimé lors de la création de la tâche ; une tâche terminée est facturée selon l'utilisation réelle, et une tâche ayant échoué ou expiré libère ou rembourse la réservation. Consultez Tâches asynchrones et polling pour le cycle de vie complet, et Obtenir le statut de l'image pour les champs de réponse.

Quand utiliser chaque mode

Utilisez async: true lorsque :

• Vous envoyez plusieurs images sources dans une seule requête.
• Votre prompt ou ensemble d'instructions est suffisamment complexe pour que le temps de génération soit imprévisible.
• Vous exécutez les éditions dans une tâche en arrière-plan, une file d'attente ou un traitement par lots plutôt que dans le cadre d'une requête utilisateur directe.

Restez en synchrone lorsque :

• Vous effectuez une édition sur une seule image avec un prompt court.
• Votre client préfère échouer rapidement plutôt que d'effectuer du polling.

Pour les appels synchrones, réglez le délai d'expiration de votre client HTTP sur au moins 120s ; les requêtes en haute résolution ou haute qualité peuvent prendre près d'une minute ou plus. Si la réponse de création renvoie tout de même status: "pending", task_id ou poll_url, basculez vers le flux de polling renvoyé.

Erreurs d'entrée à prévoir

Les échecs de récupération d'images distantes sont renvoyés sous forme d'erreurs d'entrée avant le début de la génération. Les URL inaccessibles, les dépassements de délai, les réponses 403/404, les hôtes privés ou internes, les identifiants ou fragments dans l'URL, les contenus non-image, les formats non pris en charge et les dépassements de taille renvoient une erreur 400 ou 413 et identifient l'image_url ou l'image_urls[n] en cause. Pour les ressources privées ou protégées par des en-têtes, téléversez directement les fichiers image en multipart, ou créez des références /v1/files et transmettez-les via images[].file_id.

Les modèles d'édition d'image xAI Grok Imagine (par exemple grok-imagine-image et grok-imagine-image-quality) utilisent les mêmes champs d'entrée mais limitent le nombre d'images sources à 3 ; en envoyer davantage renvoie 400 too_many_images.

Checklist d'intégration

• Ciblez POST /v1/images/edits et envoyez explicitement le paramètre model.
• Choisissez les téléversements multipart ou les références JSON selon l'emplacement où se trouvent déjà vos images.
• Envoyez exactement l'un des champs image_url, image_urls ou images[] dans les requêtes JSON ; chaque entrée de images[] comporte exactement un champ parmi image_url ou file_id.
• Utilisez async: true pour les éditions multi-images ou volumineuses ; interrogez l'adresse poll_url renvoyée jusqu'à ce que la tâche atteigne le statut completed ou failed.
• Configurez le timeout de votre client sur au moins 120 secondes pour les requêtes synchrones et gérez toute réponse pending en suivant le poll_url.
• En cas de dépassement de délai côté client, vérifiez si une tâche a été créée avant de retenter la requête de création afin d'éviter une double facturation.

Pour commencer

Interrogez GET /v1/models?recommended_for=image pour afficher les modèles d'images actuels, puis ouvrez la page détaillée d'un modèle pour confirmer les opérations et les champs de requête pris en charge avant d'envoyer une requête. Créez une clé d'API depuis la console pour tester l'endpoint d'édition avec vos propres images.