Images
Créer une image
Crée une image à partir d'un prompt
Aperçu
Utilisez GET /v1/models?recommended_for=image pour obtenir les modèles d'images actuels, puis envoyez explicitement le model sélectionné.
Chaque modèle accepte ses propres opérations et champs. GET /v1/models/{model} (Get Model) fournit l'endpoint pour chaque opération dans tokenlab.request_format_summary.request_endpoint_by_operation, ainsi que les champs, valeurs et limites acceptés pour chaque opération dans tokenlab.request_format_details.operation_constraints. Un champ non listé par le modèle peut renvoyer 400 unsupported_parameter. Une opération envoyée vers le mauvais endpoint renvoie 400 unsupported_endpoint.
Tâches d'image et résultats :
- Les modèles qui listent
asyncparmi leurs paramètres pris en charge peuvent d'abord créer une tâche : envoyezasync: true, puis interrogezGET /v1/tasks/{id}. - Les liens d'images sont conservés pendant 30 jours ; voir Rétention des données.
- Envoyez un en-tête
Idempotency-Keypour réessayer une requête de création en toute sécurité après un timeout ; voir Réessayer en toute sécurité avec une clé d'idempotence.
gpt-image-2 est un modèle GPT Image facturé au token. TokenLab suit la ventilation officielle de l'utilisation d'OpenAI pour les tokens d'entrée textuelle, d'entrée d'image, d'entrée en cache signalée et de sortie d'image ; il n'est pas facturé selon un tarif 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. Omettez size ou quality pour laisser TokenLab utiliser auto ; les valeurs personnalisées de size doivent respecter le contrat flexible WIDTHxHEIGHT documenté ci-dessous.
input_fidelity ne fait pas partie des champs actuellement pris en charge par TokenLab pour gpt-image-2 ; omettez-le, sinon la requête renvoie 400 unsupported_parameter.
Sortie SVG et GIF
gpt-image-2.6-flare et gpt-image-2.6-sunburst peuvent renvoyer un SVG ou un GIF animé au lieu d'une image matricielle. Les autres modèles rejettent ces formats.
- SVG : envoyez
output_format: "svg"etsvg: {"model": "..."}. Le modèle d'image dessine d'abord une image de référence, puis le modèle auteur écrit le SVG à partir de celle-ci.svg.modelest requis ; la liste des détails du modèle indique ses valeurs acceptées sousparameter_options(svg.model). Vous pouvez également envoyersvg.reasoning.effort. Le SVG ne fonctionne que sur ce point de terminaison, avecn: 1, et sanspartial_imagesnioutput_compression. - GIF : envoyez
output_format: "gif".frame_count(de 2 à 16, par défaut 9) définit le nombre d'images, etframe_duration_ms(de 20 à 2000, par défaut 200) définit la durée de chaque image.sizecorrespond à la taille d'une image. Le format GIF n'accepte paspartial_imagesnioutput_compression.
Le résultat se trouve dans data[].b64_json ou data[].url, comme pour les autres images. Décodez un SVG en tant que texte XML UTF-8 et enregistrez-le au format .svg ; enregistrez un GIF au format .gif.
Facturation : les jetons d'image sont facturés aux prix des jetons du modèle, et les images du GIF sont comptabilisées comme des jetons de sortie d'image. Une requête SVG facture également les jetons du modèle auteur, ce que la réponse indique dans svg_usage, aux prix de création SVG affichés sur la page du modèle.
Remarques sur le comportement des modèles
Les modèles de la famille d'images Google Gemini ne partagent pas le même contrat de sélection :
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3-pro-image,nano-banana-2.1etnano-banana-proprennent en chargeaspect_ratioainsi queresolution(1k,2k,4k) pour leurs opérations publiques text-to-image, image-to-image et image-edit.nano-banana-2prend en chargeaspect_ratioetresolution(1k,2k,4k) pour la génération text-to-image et image-to-image.gemini-3.1-flash-lite-imageetnano-banana-2-liteprennent en charge text-to-image, image-to-image et image-edit à une résolution de1kuniquement.nano-bananaprend en chargeaspect_ratiomais n'expose pas la sélection publique deresolution.- Pour l'image-to-image avec
gemini-3.1-flash-image,gemini-nano-banana-2.1,gemini-3.1-flash-lite-imageougemini-3-pro-image, utilisez cet endpoint avecoperation: "image-to-image"et des images de référence. Envoyez les requêtes d'image-edit pour ces modèles vers/v1/images/edits. - Pour les requêtes d'images de référence Nano Banana, utilisez
nano-banana-2,nano-banana-2.1,nano-banana-2-liteounano-banana-prosur cet endpoint (/v1/images/generations) avecoperation: "image-to-image"etimage_urls. Les requêtes d'image-edit pournano-banana-2,nano-banana-2.1,nano-banana-2-liteetnano-banana-proutilisent également cet endpoint, avecoperation: "image-edit". N'envoyez pas de requêtes d'images de référence Nano Banana vers/v1/images/edits. - Les images de référence sur cet endpoint peuvent être fournies sous forme de
image_url/image_urlsen JSON, ou sous forme de fichier multipartimage.images[]etfile_idne sont pas acceptés sur/v1/images/generations; ne créez des références/v1/filesque pour les modèles de/v1/images/editsqui documententimages[].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'images xAI Grok Imagine (grok-imagine-image et grok-imagine-image-2.0) prennent en charge aspect_ratio ainsi que resolution (1k, 2k). Le text-to-image utilise cet endpoint. Leurs requêtes d'image-to-image et d'image-edit utilisent /v1/images/edits.
hy-image-v3.5-preview crée une image 1024x1024 par requête à partir de texte sur cet endpoint et ne prend en charge que response_format: "url". Il modifie les images de référence sur /v1/images/edits.
Corps de la requête
Délai d'expiration de la requête synchrone : Certaines requêtes d'image renvoient l'image finale en ligne (inline) et attendent la fin de la génération. Les requêtes en haute résolution ou de haute qualité peuvent prendre près d'une minute ou plus, veillez donc à configurer le timeout de votre client HTTP à au moins 120s. Si la réponse de création inclut status: "pending", task_id ou poll_url, interrogez plutôt GET /v1/tasks/{task_id}.
Modèle à utiliser (par exemple, gpt-image-2, flux-pro-1.1 ou nano-banana-pro). Interrogez GET /v1/models?recommended_for=image pour obtenir la liste recommandée actuelle.
Description textuelle de l'image souhaitée, jusqu'à 32 000 caractères. Requis pour chaque modèle dont les détails listent prompt.
text-to-image, image-to-image ou image-edit. Lorsqu'il est omis, la valeur est image-to-image si la requête contient une image de référence, sinon text-to-image. Définissez image-edit pour les modèles dont l'opération d'édition se trouve sur cet endpoint, tel que nano-banana-pro. Une opération text-to-image avec une image de référence renvoie 400 invalid_parameter.
URL publique de l'image pour la génération image-to-image. Pour les requêtes d'image de référence Nano Banana, définissez operation sur image-to-image ; nano-banana-pro peut inclure resolution.
URLs publiques d'images de référence, jusqu'à 16. 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 publiques d'images de référence supplémentaires, jusqu'à 16, pour les modèles qui distinguent les entrées principales des références.
Fichier d'image de référence multipart pour la génération image-to-image. Utilisez ce champ lorsque l'image source est privée ou protégée par des en-têtes. Ceci est différent d'un file_id de /v1/files, qui n'est pas accepté sur cet endpoint.
1Nombre d'images à générer (1-10, dépend du modèle).
Taille de l'image. Utilisez ce champ pour les familles d'images de type OpenAI et les autres modèles qui acceptent des dimensions exactes en pixels.
Pour gpt-image-2, size accepte auto ou WIDTHxHEIGHT. Les dimensions personnalisées doivent toutes deux être des multiples de 16, le bord le plus long doit être d'au plus 3840px, le rapport longueur/largeur doit être d'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 des détails actuels du modèle TokenLab pour gpt-image-2.
Pour les modèles d'images Google avec des niveaux de résolution (gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image, nano-banana-2, nano-banana-2.1 et nano-banana-pro), size accepte une taille de sortie issue du tableau des tailles du modèle, comme 1376x768 (16:9 en 1K), ou un niveau de résolution : 1K, 2K ou 4K. TokenLab envoie un niveau sous forme de resolution, de sorte que la requête et son prix sont identiques à ceux avec resolution. Un niveau que le modèle ne prend pas en charge (par exemple 2K sur gemini-3.1-flash-lite-image), ou un niveau différent de resolution, renvoie 400 avec le code invalid_image_size_contract et les allowed_resolutions du modèle. Pour ces modèles, la forme recommandée est aspect_ratio avec resolution.
Sélecteur de format d'image dépendant du modèle.
Les valeurs courantes pour la famille d'images Google incluent 1:1, 16:9, 9:16, 3:2 et 2:3.
Résolution de sortie dépendante du modèle. gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2, nano-banana-2.1 et nano-banana-pro prennent en charge 1k, 2k et 4k ; les modèles d'images Grok Imagine prennent en charge 1k et 2k. Omettez ce champ sauf si le modèle et l'opération sélectionnés le prennent explicitement en charge.
Qualité de l'image. Les modèles GPT Image tels que gpt-image-2 utilisent auto, low, medium ou high. D'autres modèles peuvent utiliser des valeurs différentes ; vérifiez les détails du modèle avant d'envoyer une valeur autre que celle par défaut.
Format de fichier de l'image : png, jpeg ou webp. gpt-image-2.6-flare et gpt-image-2.6-sunburst acceptent également svg et gif ; voir Sortie SVG et GIF.
Paramètres SVG, uniquement avec output_format: "svg". model (requis) sélectionne le modèle auteur qui écrit le SVG. reasoning.effort définit optionnellement son effort de raisonnement.
9Nombre d'images GIF, de 2 à 16. Uniquement avec output_format: "gif".
200Durée de chaque image GIF en millisecondes, de 20 à 2000. Uniquement avec output_format: "gif".
Format de retour des images : url ou b64_json.
- Omis : lorsque le modèle renvoie les octets de l'image, chaque image figure dans
data[].b64_json, ainsi que dansdata[].urlsi TokenLab l'a stockée. Lorsque le modèle renvoie un lien, chaque image figure dansdata[].url. url: chaque image figure uniquement dansdata[].url.b64_json: chaque image figure uniquement dansdata[].b64_jsonsous forme de données Base64.
Les liens sont des URL TokenLab vers les résultats médias. Ils restent valides pendant 30 jours. Voir Rétention des données.
falseDéfinissez sur true pour créer une tâche en premier. Seuls les modèles qui listent async parmi leurs paramètres pris en charge l'acceptent, par exemple gpt-image-2, flux-pro-1.1, nano-banana-pro et seedream-5.0-lite ; pour tout autre modèle, la requête renvoie 400 unsupported_async_mode. Les tâches d'image asynchrones terminées renvoient des URLs indépendamment du response_format demandé ; utilisez des requêtes synchrones lorsque vous avez besoin de b64_json.
Sélecteur de style optionnel. N'envoyez ce paramètre que si 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.
Certains modèles acceptent également des champs tels que negative_prompt, seed, width, height, steps, guidance_scale ou mask_url. Ne les envoyez que lorsque les détails du modèle les listent. stream: true n'est pas pris en charge et renvoie 400 unsupported_parameter.
Réponse
Réponse inline
Horodatage Unix de création.
Tableau des images générées.
Chaque objet contient :
url(string) : URL TokenLab vers le résultat média de l'image, valide pendant 30 jours. Non présente lorsqueresponse_formatestb64_json. Lorsqueresponse_formatest omis, elle est absente si TokenLab n'a pas pu stocker l'image.b64_json(string) : Données de l'image en Base64. Présente lorsqueresponse_formatestb64_json, ou lorsqu'il est omis et que le modèle renvoie les octets de l'image.revised_prompt(string) : Révision facultative du prompt, lorsque le modèle sélectionné en renvoie une
Nombre de tokens (input_tokens, output_tokens, total_tokens et leurs détails) pour les modèles facturés au token tels que gpt-image-2, le cas échéant.
Nombre de tokens du modèle de création SVG (model, input_tokens, output_tokens, reasoning_tokens, total_tokens). Présent uniquement pour les sorties SVG. Ces tokens ne sont pas inclus dans usage et sont facturés aux tarifs de création SVG.
Réponse de tâche asynchrone
Définissez async: true sur un modèle qui le prend en charge pour créer une tâche au lieu d'attendre l'image finale dans la requête de création. La réponse inclut status: "pending", task_id et poll_url. Interrogez /v1/tasks/{task_id} jusqu'à ce que la tâche atteigne completed ou failed.
Les tâches d'images asynchrones renvoient uniquement les URLs des images finales. Si vous avez besoin de données brutes d'image en b64_json, utilisez une requête synchrone.
La facturation peut réserver le montant estimé lors de la création de la tâche. Les tâches terminées sont facturées selon l'utilisation réelle, et les tâches ayant échoué ou expiré sont libérées ou remboursées.
Horodatage Unix de création.
Identifiant unique de la tâche pour le polling.
Statut initial : pending.
URL relative à interroger pour obtenir les résultats, par exemple /v1/tasks/{id}.
Vide tant que la tâche est en attente. Les tâches d'images terminées renvoient les URLs des images générées dans data[].url.
Lorsque vous recevez status: "pending", appelez GET /v1/tasks/{task_id} pour récupérer le résultat.
Requête
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'];Exemple de famille d'images avec ratio uniquement : pour nano-banana, envoyez aspect_ratio mais omettez resolution :
{
"model": "nano-banana",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}Exemple d'image de référence Nano Banana Pro : envoyez la requête à /v1/images/generations, et non à /v1/images/edits. resolution est optionnel et peut être défini sur 1k, 2k ou 4k :
{
"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"
}Exemple de téléversement multipart direct pour des images sources locales ou privées. Ne transmettez pas de file_id à /v1/images/generations :
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"Réponse
{
"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..."
}
]
}Erreurs
Les erreurs de requête renvoient 400 (413 pour les téléversements trop volumineux) avec un error.code. Codes courants pour les requêtes d'images :
| Code | Cause |
|---|---|
unsupported_parameter | Le modèle ne liste pas ce champ, ou stream est défini sur true |
unsupported_operation | Le modèle ne dispose pas d'une telle operation |
unsupported_endpoint | L'opération pour ce modèle se trouve sur un autre endpoint, tel que /v1/images/edits |
unsupported_async_mode | Le modèle ne prend pas en charge async: true |
invalid_resolution, invalid_aspect_ratio, invalid_parameter_value, too_many_items | Une valeur se situe en dehors de ce que le modèle accepte. L'erreur indique les valeurs acceptées |
invalid_image_size_contract | Une size ou un niveau non pris en charge par le modèle, ou qui entre en conflit avec resolution |
prompt_too_long | Le prompt est plus long que ce que le modèle accepte |
request_too_large, file_too_large | Un téléversement dépasse la limite de taille (50 MiB par fichier, 200 MiB pour l'ensemble des entrées) |
Pour le solde (402), les limites de débit (429) et les règles de réessai, voir Gestion des erreurs.
Choisir un modèle
Interrogez GET /v1/models?recommended_for=image ou consultez la page Modèles pour connaître la disponibilité actuelle, les fonctionnalités et les tarifs.
Ne définissez pas en dur un modèle comme étant toujours synchrone ou toujours asynchrone. Une requête sans async: true peut tout de même renvoyer status: "pending" ; dès lors que la réponse de création contient status: "pending" ou status: "processing", interrogez GET /v1/tasks/{task_id} jusqu'à la fin de l'opération.
Gestion des réponses basées sur des tâches
Pour les modèles d'images, vérifiez toujours si la réponse contient status: "pending" / status: "processing" :
import requests
import time
def generate_image(prompt, model="gpt-image-2"):
# Create image request
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()
# Check if task-based
if data.get("status") in ("pending", "processing"):
task_id = data["task_id"]
print(f"Image task started: {task_id}")
# Poll for result
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
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)
raise TimeoutError(f"Image task {task_id} did not finish in time")
else:
# Inline response
return data["data"][0]["url"]
# Usage
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")Exemple avec Hy Image 3.5 Preview. Il accepte uniquement la size 1024x1024 et n valant 1 :
{
"model": "hy-image-v3.5-preview",
"prompt": "A yellow lemon on a white table",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Autorisation
BearerAuth Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.
Emplacement: header
En-têtes
Politique de livraison par requête. Remplace les valeurs par défaut de la clé API et de l'espace de travail. Tente automatiquement TokenLab Verified en premier et peut basculer une fois vers Official uniquement avant la sortie, l'acceptation de la requête ou la création de ressource persistante.
Valeurs possibles
- "auto"
- "verified"
- "official"
Clé optionnelle qui permet de réessayer une requête d'image en toute sécurité si la requête a créé une tâche. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque requête. Une tentative avec la même clé et le même corps renvoie alors cette tâche et ne crée, ne distribue ni ne facture une seconde tâche. Pour une requête qui renvoie l'image directement, une tentative avec la même clé peut renvoyer un statut de tâche au lieu de l'image, ou 409 avec idempotent_response_not_replayable. Un corps différent avec une clé déjà acceptée est rejeté ; le code de statut et le code d'erreur pour ce cas ne sont pas garantis. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.
1 <= length <= 255Réponse
application/json
application/json
application/json
application/json
application/json
application/json
application/json