Génération d'Image

TokenLab prend en charge la génération d’images à partir de texte, d’images à partir d’images et l’édition d’images via des points de terminaison d’image publics. Les modèles d’image ne partagent pas un ensemble de paramètres universel, donc les clients de production doivent d’abord choisir le point de terminaison, puis choisir le modèle, puis envoyer uniquement les champs pris en charge par ce modèle.

Quand Utiliser Chaque Point de Terminaison

Flux de travail utilisateur	Point de terminaison	Utiliser quand	Éviter quand
Texte à image	`POST /v1/images/generations`	L’utilisateur commence uniquement par un prompt	Vous avez besoin d’un flux d’édition d’image GPT officiel
Image à image	`POST /v1/images/generations`	Les documents du modèle font référence à des images via `operation: "image-to-image"` plus `image_url`, `image_urls`, ou `reference_image_urls`	Le modèle attend une entrée d’édition multipart
Édition d’image	`POST /v1/images/edits`	Vous éditez une image existante avec un modèle d’édition pris en charge tel qu’un modèle de la famille GPT Image	Vous utilisez la génération d’image à partir d’image de style Nano Banana
Variation	`POST /v1/images/variations`	Vous maintenez une intégration compatible avec les variations héritées	Vous construisez un nouveau flux d’image de référence
Statut	`GET /v1/tasks/{id}`	Une réponse de création retourne `task_id`, `status: "pending"`, ou `poll_url`	La réponse de création contient déjà les `data[]` finales

Envoyez toujours model. Les points de terminaison d’image ne s’appuient intentionnellement pas sur un modèle par défaut implicite historique pour le trafic de production.

Choisissez Un Modèle

Commencez par la découverte de modèles, puis inspectez le contrat TokenLab du modèle sélectionné :

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Pour les modèles non liés aux chats, la réponse de la liste peut inclure tokenlab.public_contract_summary. Les pages de détails des modèles peuvent exposer le tokenlab.public_contract complet. Utilisez ces champs pour confirmer :

L’opération prise en charge, telle que text-to-image, image-to-image, ou image-edit.
Le point de terminaison de requête attendu par le modèle.
Quelle forme utiliser pour les références, comme image_url, image_urls, reference_image_urls, multipart image, ou JSON images[].
Si le modèle accepte size, aspect_ratio, resolution, quality, background, output_format, ou response_format.

Règles de Forme de Requête

Les requêtes de style gpt-image-2 utilisent des champs size, quality, et d’édition similaires à OpenAI. Laissez de côté les champs optionnels lorsque vous souhaitez que le modèle ou TokenLab utilise des valeurs par défaut automatiques.
Les familles d’images Gemini et Nano Banana utilisent généralement aspect_ratio; n’envoyez resolution que lorsque le contrat du modèle l’expose.
L’image à image Nano Banana appartient à /v1/images/generations avec operation: "image-to-image" et des URLs d’images de référence.
/v1/images/generations n’accepte pas images[] ou file_id au niveau supérieur; ce sont des formes de flux d’édition.
Les références d’images distantes doivent être des URLs publiques http ou https. N’envoyez pas d’URLs de réseau privé, de credentials intégrés, de fragments d’URL, ou d’URLs signées qui pourraient expirer avant le début du traitement.

Exemple Texte-à-Image

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Une photo de produit propre d'une tasse à café en céramique sur un bureau en noyer",
    "size": "1024x1024",
    "response_format": "url"
  }'

Exemple Image de Référence

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "operation": "image-to-image",
    "prompt": "Conservez la forme du produit, changez l'arrière-plan pour un éclairage de studio lumineux",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Gestion des Résultats

Les réponses d’image peuvent être synchrones ou asynchrones :

Les réponses synchrones retournent les data[] finales avec url ou b64_json.
Les réponses asynchrones retournent id, task_id, status, et généralement poll_url.
Préférez poll_url lorsqu’il est présent. Si vous avez besoin d’une route fixe, interrogez GET /v1/tasks/{id}.
Utilisez des requêtes synchrones lorsque vous avez spécifiquement besoin de b64_json; les résultats d’image asynchrones sont orientés URL.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Conservez l’URL d’image retournée, l’ID de tâche, le modèle, et votre propre ID utilisateur/travail. Ne continuez pas à interroger après un statut terminal.

Liste de Vérification de Production

Validez les entrées utilisateur avant d’appeler TokenLab : longueur du prompt, nombre d’images, accessibilité des URLs, et type de fichier.
Réglez les délais d’attente HTTP suffisamment élevés pour les requêtes synchrones haute résolution. Utilisez le mode asynchrone lorsque disponible pour un travail long.
Stockez request_id, task_id, poll_url, modèle, point de terminaison, et forme de requête assainie pour le support.
En cas de délai d’attente client, vérifiez si une tâche a été créée avant de réessayer la requête de création.
Réconciliez le coût avec les enregistrements d’utilisation et billing_transaction_id lorsqu’il est présent, pas avec les IDs de tâche du fournisseur.

Erreurs Courantes

Symptôme	Cause probable	Solution
`400` avec `param: "model"`	Modèle explicite manquant	Interrogez `/v1/models?recommended_for=image` et envoyez `model`
Champ non pris en charge	Le champ n’est pas dans le contrat public de ce modèle	Supprimez le champ ou choisissez un modèle/point de terminaison qui le documente
Pas de `b64_json` sur le résultat asynchrone	Les tâches d’image asynchrones retournent des résultats orientés URL	Utilisez le mode synchrone pour la sortie base64
Image de référence rejetée	Mauvais point de terminaison ou URL privée/expirée	Correspondre à la forme de référence documentée du modèle et utiliser des URLs accessibles

Référence API

Sujet	Référence
Créer une Image	Créer une Image
Éditer une Image	Éditer une Image
Créer une Variation d’Image	Créer une Variation d’Image
Obtenir le Statut de l’Image	Obtenir le Statut de l’Image
Obtenir le Statut de la Tâche	Obtenir le Statut de la Tâche

​Quand Utiliser Chaque Point de Terminaison

​Choisissez Un Modèle

​Règles de Forme de Requête

​Exemple Texte-à-Image

​Exemple Image de Référence

​Gestion des Résultats

​Liste de Vérification de Production

​Erreurs Courantes

​Référence API