Créer une image - TokenLab

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, partial_images 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. Note de compatibilite : si une requete gpt-image-2 contient input_fidelity, TokenLab le supprime avant le transfert, car GPT Image 2 traite deja automatiquement les entrees image en haute fidelite.

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-preview, gemini-3-pro-image-preview, nano-banana-2 et nano-banana-pro prennent en charge aspect_ratio ainsi que resolution (1k, 2k, 4k) pour la génération texte-vers-image.
gemini-2.5-flash-image, nano-banana et nano-banana-edit prennent en charge aspect_ratio, mais n’exposent pas de sélection publique de resolution.
gemini-2.0-flash-preview-image-generation est documenté ici comme un modèle texte-vers-image piloté uniquement par le prompt.
Pour les requêtes avec image de référence nano-banana, nano-banana-2 et nano-banana-pro, utilisez 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 image-to-image Nano Banana, omettez resolution. nano-banana-2 et nano-banana-pro n’exposent resolution que pour le texte-vers-image, et nano-banana ne l’expose pas.
Les images de référence sur cet endpoint peuvent être fournies via 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’utilisent que pour les modèles /v1/images/edits qui documentent 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é et route upstream vers 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é.

model

string

défaut:"dall-e-3"

Modèle à utiliser (par exemple gpt-image-2, dall-e-3, flux-pro, midjourney).

prompt

string

requis

Description textuelle de l’image souhaitée.

image_url

string

URL HTTPS publique d’image de référence pour la génération image-to-image. Pour la famille Nano Banana, définissez operation sur image-to-image et omettez resolution sauf si le modèle la prend explicitement en charge pour cette opération.

image_urls

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.

reference_image_urls

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.

image

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).

size

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 contrat public TokenLab actuel pour gpt-image-2.Pour les familles d’images Google Gemini, size sert d’alias de compatibilité mappé vers le contrat public 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.

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.

resolution

string

Sélecteur de résolution de sortie dépendant du modèle.Pris en charge sur gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, nano-banana-2, nano-banana-pro et les familles haute résolution similaires. 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.

quality

string

défaut:"standard"

Qualité de l’image. Les modèles DALL-E utilisent standard ou hd; les modèles GPT Image comme gpt-image-2 utilisent auto, low, medium ou high.

response_format

string

défaut:"url"

Format de réponse : url ou b64_json. La valeur par défaut est url.Pour les routes gpt-image-2 Azure Official ou compatibles Azure, TokenLab ne transmet pas response_format à l’upstream. La passerelle reçoit toujours les données d’image upstream en b64_json ; pour les requêtes url, elle 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 de retomber sur Base64. Pour b64_json, le Base64 brut est renvoyé.

async

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.

style

string

défaut:"vivid"

Style pour DALL-E 3 : vivid ou natural.

user

string

Identifiant unique pour l’utilisateur final.

Réponse

Réponse inline

created

integer

Horodatage Unix de création.

data

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) : Le prompt utilisé (DALL-E 3)

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.

created

integer

Horodatage Unix de création.

task_id

string

Identifiant unique de la tâche pour l’interrogation.

status

string

Statut initial : pending.

poll_url

string

URL relative pour interroger les résultats, par exemple /v1/tasks/{id}.

data

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.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}

Modèles disponibles

Modèle	Type	Fonctionnalités
`dall-e-3`	Généralement inline	Meilleure qualité, amélioration du prompt
`dall-e-2`	Généralement inline	Plus rapide, plus abordable
`flux-pro`	Souvent basé sur une tâche	Photoréaliste, haute qualité
`flux-schnell`	Généralement inline	Très rapide
`midjourney`	Souvent basé sur une tâche	Style artistique
`ideogram-v3`	Souvent basé sur une tâche	Meilleur rendu du texte
`stable-diffusion-3`	Généralement inline	Open source, personnalisable

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" :

import requests
import time

def generate_image(prompt, model="midjourney"):
    # Créer la requête d'image
    response = requests.post(
        "https://api.tokenlab.sh/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt}
    )
    data = response.json()

    # Vérifier s'il s'agit d'une tâche
    if data.get("status") == "pending":
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Tâche image démarrée : {task_id}")

        # Interroger le résultat
        while True:
            status_resp = requests.get(
                f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"}
            )
            status_data = status_resp.json()

            if status_data["status"] == "completed":
                return status_data["data"][0]["url"]
            elif status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)
    else:
        # Réponse synchrone
        return data["data"][0]["url"]

# Utilisation
url = generate_image("a beautiful sunset over mountains", model="midjourney")
print(f"Image générée : {url}")

Documentation Index

​Aperçu

​Notes sur le comportement des modèles

​Corps de la requête

​Réponse

​Réponse inline

​Réponse de tâche asynchrone

​Modèles disponibles

​Gestion des réponses basées sur une tâche

Aperçu

Notes sur le comportement des modèles

Corps de la requête

Réponse

Réponse inline

Réponse de tâche asynchrone

Modèles disponibles

Gestion des réponses basées sur une tâche