Créer une image

AperçuCopy Anchor Link

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 des 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èlesCopy Anchor Link

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 et resolution (1k, 2k, 4k) pour les générations text-to-image et image-to-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 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.
• 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êteCopy Anchor Link

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

RéponseCopy Anchor Link

Réponse inlineCopy Anchor Link

Réponse de tâche asynchroneCopy Anchor Link

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.

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",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)

print(response.data[0].url)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.generate({
  model: 'gemini-3-pro-image',
  prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
  aspect_ratio: '16:9',
  resolution: '2k'
});

console.log(response.data[0].url);

<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gemini-3-pro-image',
        'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
        'aspect_ratio' => '16:9',
        'resolution' => '2k'
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];

{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

{
  "model": "nano-banana-pro",
  "prompt": "Create a clean cinematic character image based on the reference images",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/reference-1.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=nano-banana-pro" \
  -F "prompt=Create a clean cinematic character image based on this reference" \
  -F "operation=image-to-image" \
  -F "image=@reference.png" \
  -F "aspect_ratio=1:1" \
  -F "resolution=2k"

{
  "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 disponiblesCopy Anchor Link

Consultez GET /v1/models?recommended_for=image pour les modèles d’image, capacités et prix actuels.

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âcheCopy Anchor Link

Pour les modèles d’image, vérifiez toujours si la réponse contient status: "pending" / status: "processing" :

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # 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, "async": True},
        timeout=120
    )
    response.raise_for_status()
    data = response.json()

    # Vérifier s'il s'agit d'une tâche
    if data.get("status") in ("pending", "processing"):
        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"},
                timeout=30
            )
            status_resp.raise_for_status()
            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="gpt-image-2")
print(f"Image générée : {url}")

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}