> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Créer une image
> Crée une image à partir d’un prompt
## 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`. 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é.
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é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.
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`.
Lorsque vous recevez `status: "pending"`, utilisez `poll_url` ou `GET /v1/tasks/{task_id}` pour récupérer le résultat.
```bash cURL theme={null}
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",
"n": 1
}'
```
```python Python theme={null}
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",
aspect_ratio="16:9",
resolution="2k",
n=1
)
print(response.data[0].url)
```
```javascript JavaScript theme={null}
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',
n: 1
});
console.log(response.data[0].url);
```
```php PHP theme={null}
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',
'n' => 1
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
```
Exemple pour les modèles limités au ratio : pour `gemini-2.5-flash-image`, `nano-banana` ou `nano-banana-edit`, envoyez `aspect_ratio` mais omettez `resolution` :
```json theme={null}
{
"model": "gemini-2.5-flash-image",
"prompt": "A clean editorial product shot of a citrus soda can",
"aspect_ratio": "16:9"
}
```
Exemple Nano Banana Pro avec image de référence : envoyez la requête à `/v1/images/generations`, pas à `/v1/images/edits`. `resolution` est facultatif et peut être défini sur `1k`, `2k` ou `4k` :
```json theme={null}
{
"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"
}
```
Pour les images source privées ou locales, utilisez un upload multipart direct. Ne transmettez pas de `file_id` à `/v1/images/generations` :
```bash theme={null}
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"
```
```json Inline Response theme={null}
{
"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..."
}
]
}
```
```json Async Task Response theme={null}
{
"created": 1706000000,
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"data": []
}
```
## 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.
| 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 |
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"` :
```python theme={null}
import requests
import time
def generate_image(prompt, model="flux-pro"):
# 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="flux-pro")
print(f"Image générée : {url}")
```