Aperçu
Pour les agents de code, commencez par découvrir la shortlist d’images actuellement recommandées avecGET /v1/models?recommended_for=image, puis envoyez explicitement le model sélectionné à cet endpoint.
gpt-image-2 est un modèle GPT Image facturé au token. TokenLab suit le détail officiel usage d’OpenAI pour facturer les tokens d’entrée texte, d’entrée image, d’entrée en cache lorsqu’ils sont indiqués, et de sortie image ; ce n’est pas un modèle à prix fixe par image.
Pour la génération d’images avec gpt-image-2, les paramètres publics pris en charge sont prompt, n, size, quality, response_format, async, background, output_format, output_compression ou compression, moderation et user. Si size ou quality est omis, TokenLab utilise auto ; les valeurs size personnalisées doivent suivre le contrat flexible WIDTHxHEIGHT documenté ci-dessous.
input_fidelity ne fait pas partie du champs pris en charge actuel de TokenLab pour gpt-image-2 ; omettez-le, sinon la requete renvoie 400 unsupported_parameter.
Notes sur le comportement des modèles
Les modèles de la famille image Gemini de Google n’utilisent pas exactement le même contrat de sélection :gemini-3.1-flash-image,gemini-3-pro-imageetnano-banana-proprennent en chargeaspect_ratioainsi queresolution(1k,2k,4k) pour leurs opérations publiques texte-vers-image et image-edit/image-to-image.nano-banana-2prend en chargeaspect_ratioainsi queresolution(1k,2k,4k) uniquement pour le texte-vers-image dans le contrat TokenLab actuel.gemini-2.5-flash-image,nano-bananaetnano-banana-editprennent en chargeaspect_ratio, mais n’exposent pas de sélection publiqueresolution.- Pour les requêtes Nano Banana avec image de référence, utilisez
nano-banana-editounano-banana-prosur cet endpoint (/v1/images/generations) avecoperation: "image-to-image"etimage_urls. N’envoyez pas ces requêtes Nano Banana à/v1/images/edits. - Pour les requêtes Nano Banana image-to-image,
nano-banana-propeut inclureresolution(1k,2k,4k) ;nano-banana-editdoit l’omettre.nano-bananaetnano-banana-2sont des modèles texte-vers-image dans le détails du modèle actuel. - Les images de référence sur cet endpoint peuvent être fournies en JSON
image_url/image_urls, ou comme fichier multipartimage./v1/images/generationsn’accepte pasimages[]nifile_id; les références/v1/filesne s’appliquent qu’aux modèles/v1/images/editsqui documentent explicitementimages[].file_id.
aspect_ratio et n’envoyez resolution que lorsque le modèle la prend explicitement en charge.
Les modèles d’image xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality et le legacy grok-imagine-image-pro) prennent en charge aspect_ratio ainsi que resolution (1k, 2k). grok-imagine-image-pro reste disponible comme ID de compatibilité pour grok-imagine-image-quality.
Corps de la requête
Timeout des requêtes synchrones : certains fournisseurs d’images routés renvoient l’image finale inline et attendent la fin de la génération. Les requêtes haute résolution ou haute qualité peuvent prendre près d’une minute, voire plus ; configurez donc le timeout de votre client HTTP à au moins120s. Si la réponse de création contient status: "pending", task_id ou poll_url, suivez plutôt le poll_url renvoyé.
Modèle à utiliser (par exemple
gpt-image-2, flux-pro, qwen-image-plus ou nano-banana-pro). Consultez GET /v1/models?recommended_for=image pour la liste recommandée actuelle.Description textuelle de l’image souhaitée.
URL HTTPS publique d’image de référence pour la génération image-to-image. Pour les requêtes Nano Banana avec image de référence, définissez
operation sur image-to-image ; nano-banana-pro peut inclure resolution, tandis que nano-banana-edit doit l’omettre.URLs HTTPS publiques d’images de référence. Utilisez ce champ pour une ou plusieurs images de référence dans les requêtes JSON.
file_id et images[] ne sont pas pris en charge sur cet endpoint.URLs d’images de référence supplémentaires propres au modèle pour les fournisseurs qui distinguent les images d’entrée principales des références.
Fichier image de référence multipart pour la génération image-to-image. Utilisez-le lorsque l’image source est privée ou protégée par en-têtes. Ce n’est pas un
file_id /v1/files, et cet endpoint n’accepte pas file_id.Nombre d’images à générer (1-10, selon le modèle).
Taille de l’image. Utilisez ce champ pour les familles d’images de style OpenAI et les autres modèles qui acceptent des tailles exactes en pixels.Pour
gpt-image-2, size accepte auto ou WIDTHxHEIGHT. Les dimensions personnalisées doivent être des multiples de 16 sur les deux axes, le bord le plus long doit être au plus 3840px, le rapport bord long/bord court doit être au plus 3:1, et le nombre total de pixels doit être compris entre 655,360 et 8,294,400. aspect_ratio et resolution ne font pas partie du détails du modèle TokenLab actuel pour gpt-image-2.Pour les familles d’images Google Gemini, size sert d’alias de compatibilité mappé vers le détails du modèle aspect_ratio du modèle et, lorsque c’est pris en charge, vers resolution. Pour ces modèles, préférez envoyer directement aspect_ratio.Sélecteur de ratio d’aspect dépendant du modèle.Les valeurs courantes pour les familles d’images Google incluent
1:1, 16:9, 9:16, 3:2 et 2:3.Sélecteur de résolution de sortie dépendant du modèle.Pris en charge sur
gemini-3.1-flash-image et gemini-3-pro-image pour texte-vers-image et image-edit, sur nano-banana-pro pour texte-vers-image et image-to-image, et sur nano-banana-2 uniquement pour texte-vers-image. Les valeurs typiques sont 1k, 2k et 4k. N’envoyez pas ce paramètre aux familles d’images Gemini limitées au ratio, sauf si le modèle le documente explicitement. Pour les modèles d’image xAI Grok Imagine, utilisez 1k ou 2k.Qualité d’image. Les modèles GPT Image comme
gpt-image-2 utilisent auto, low, medium ou high. D’autres familles d’images peuvent utiliser des valeurs propres au fournisseur ; vérifiez les métadonnées du modèle avant d’envoyer des valeurs non par défaut.Format de réponse :
url ou b64_json. La valeur par défaut est url.Pour les requêtes gpt-image-2 Azure Official ou compatibles Azure, TokenLab reçoit les données d’image en b64_json. Pour les requêtes url, TokenLab téléverse chaque image vers le CDN et renvoie data[].url. Si le stockage CDN est indisponible ou si le téléversement échoue, la requête échoue au lieu d’être convertie en réponse Base64. Pour b64_json, le Base64 brut est renvoyé.Définissez sur
true avec gpt-image-2 ou les modèles d’image officiels FLUX/BFL pour créer d’abord une tâche. Les tâches image asynchrones terminées renvoient des URL, quel que soit le response_format demandé ; utilisez des requêtes synchrones si vous avez besoin de b64_json.Sélecteur de style optionnel. Envoyez-le uniquement lorsque le modèle sélectionné le documente explicitement ; omettez-le pour
gpt-image-2 sauf indication contraire dans les métadonnées du modèle.Identifiant unique pour l’utilisateur final.
Réponse
Réponse inline
Horodatage Unix de création.
Tableau des images générées.Chaque objet contient :
url(string) : URL de l’image généréeb64_json(string) : Image encodée en Base64 (si demandée)revised_prompt(string): Révision optionnelle du prompt lorsque le modèle sélectionné la renvoie
Réponse de tâche asynchrone
Définissezasync: true avec gpt-image-2 ou les modèles d’image officiels FLUX/BFL pour créer une tâche au lieu d’attendre l’image finale dans la requête de création. La réponse contient status: "pending", task_id et poll_url. Interrogez /v1/tasks/{task_id} jusqu’à ce que la tâche passe à completed ou failed.
Les tâches image asynchrones ne renvoient que les URL finales. Si vous avez besoin des données image brutes b64_json, utilisez une requête synchrone.
La création de la tâche peut réserver le montant estimé. Les tâches terminées sont facturées selon l’usage réel ; les tâches échouées ou expirées libèrent ou remboursent la réserve.
Horodatage Unix de création.
Identifiant unique de la tâche pour l’interrogation.
Statut initial :
pending.URL relative pour interroger les résultats, par exemple
/v1/tasks/{id}.Vide tant que la tâche est en attente. Les tâches d’image terminées renvoient les URL d’image générées dans
data[].url.status: "pending", utilisez poll_url ou GET /v1/tasks/{task_id} pour récupérer le résultat.
Modèles disponibles
Ce sont des exemples de modèles actuels, pas un catalogue fixe. ConsultezGET /v1/models?recommended_for=image ou la page Models pour la disponibilité et les prix à jour.
| Modèle | Type | Fonctionnalités |
|---|---|---|
gpt-image-2 | Inline ou basé sur une tâche | Modèle GPT Image facturé au token, tailles flexibles |
flux-pro | Souvent basé sur une tâche | Photoréaliste, haute qualité |
qwen-image-plus | Souvent basé sur une tâche | Bon rendu du texte et respect du prompt |
nano-banana-pro | Souvent basé sur une tâche | Workflows avec images de référence et sortie haute résolution |
grok-imagine-image | Souvent basé sur une tâche | Génération d’images xAI avec choix du ratio et de la résolution |
ideogram-v3 | Souvent basé sur une tâche | Bon rendu du texte |
status: "pending", suivez poll_url et interrogez jusqu’à la fin du traitement.
Gestion des réponses basées sur une tâche
Pour les modèles d’image, vérifiez toujours si la réponse contientstatus: "pending" :