Skip to main content

Aperçu

Pour les agents de code, commencez par découvrir la shortlist d’images actuellement recommandées avec GET /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. background accepte auto ou opaque ; transparent n’est pas pris en charge. 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-image et nano-banana-pro prennent en charge aspect_ratio ainsi que resolution (1k, 2k, 4k) pour leurs opérations publiques texte-vers-image et image-edit/image-to-image.
  • nano-banana-2 prend en charge aspect_ratio ainsi que resolution (1k, 2k, 4k) uniquement pour le texte-vers-image dans le contrat TokenLab actuel.
  • gemini-2.5-flash-image, nano-banana et nano-banana-edit prennent en charge aspect_ratio, mais n’exposent pas de sélection publique resolution.
  • Pour les requêtes Nano Banana avec image de référence, utilisez nano-banana-edit ou nano-banana-pro sur cet endpoint (/v1/images/generations) avec operation: "image-to-image" et image_urls. N’envoyez pas ces requêtes Nano Banana à /v1/images/edits.
  • Pour les requêtes Nano Banana image-to-image, nano-banana-pro peut inclure resolution (1k, 2k, 4k) ; nano-banana-edit doit l’omettre. nano-banana et nano-banana-2 sont 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 multipart image. /v1/images/generations n’accepte pas images[] ni file_id ; les références /v1/files ne s’appliquent qu’aux modèles /v1/images/edits qui documentent explicitement images[].file_id.
Pour les familles d’images Google, privilégiez 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 moins 120s. Si la réponse de création contient status: "pending", task_id ou poll_url, suivez plutôt le poll_url renvoyé.
string
requis
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.
string
requis
Description textuelle de l’image souhaitée.
string
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.
string[]
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.
string[]
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.
file
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.
integer
défaut:"1"
Nombre d’images à générer (1-10, selon le modèle).
string
défaut:"1024x1024"
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.
string
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.
string
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.
string
défaut:"standard"
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.
string
défaut:"url"
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é.
boolean
défaut:"false"
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.
string
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.
string
Identifiant unique pour l’utilisateur final.

Réponse

Réponse inline

integer
Horodatage Unix de création.
array
Tableau des images générées.Chaque objet contient :
  • url (string) : URL de l’image générée
  • b64_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éfinissez async: 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.
integer
Horodatage Unix de création.
string
Identifiant unique de la tâche pour l’interrogation.
string
Statut initial : pending.
string
URL relative pour interroger les résultats, par exemple /v1/tasks/{id}.
array
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.
Lorsque vous recevez 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. Consultez GET /v1/models?recommended_for=image ou la page Models pour la disponibilité et les prix à jour. Ne codez pas un modèle comme toujours synchrone ou toujours asynchrone. Si la réponse de création renvoie 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 contient status: "pending" :