Guides médias
Génération d'images
Générez ou modifiez des images et gérez les fichiers terminés ou les tâches asynchrones
TokenLab prend en charge la conversion de texte en image, d'image en image et l'édition d'images. Les paramètres diffèrent selon le modèle ; vérifiez donc les champs de requête du modèle sélectionné avant d'envoyer la requête.
Choisir un endpoint
| Ce dont vous avez besoin | Endpoint | À utiliser quand | À éviter pour |
|---|---|---|---|
| Texte vers image | POST /v1/images/generations | L'utilisateur commence uniquement avec du texte | Modifier un fichier image GPT existant |
| Image vers image | POST /v1/images/generations | Le modèle accepte operation: "image-to-image" et des URL d'images | Modèles nécessitant une entrée d'édition multipart |
| Édition d'image | POST /v1/images/edits | Un modèle d'édition pris en charge modifie une image existante | Génération de référence de style Nano Banana |
| Variation | POST /v1/images/variations | Une intégration existante utilise déjà l'API de variations | Une nouvelle fonctionnalité d'image de référence |
| Statut | GET /v1/tasks/{id} | Une réponse de création renvoie task_id, status: "pending" ou poll_url | La réponse de création contient déjà data[] final |
Envoyez toujours model ; les API d'image ne choisissent pas de modèle par défaut pour vous.
Choisir un modèle
Trouvez les modèles d'image actuels avec :
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"Ouvrez les détails du modèle sélectionné pour confirmer :
- L'opération prise en charge, telle que
text-to-image,image-to-imageouimage-edit. - L'endpoint de requête attendu par le modèle.
- Comment envoyer des références :
image_url,image_urls,reference_image_urls,imageen multipart, ouimages[]en JSON. - Si le modèle accepte
size,aspect_ratio,resolution,quality,background,output_formatouresponse_format.
Champs spécifiques au modèle
- Les requêtes de style
gpt-image-2utilisent des champssize,qualityet d'édition similaires à ceux d'OpenAI. Pour la génération et les modifications avec ce modèle,backgroundaccepteautoouopaque;transparentn'est pas pris en charge. Omettez les champs optionnels pour utiliser les valeurs par défaut automatiques. - Les familles d'images Gemini et Nano Banana utilisent généralement
aspect_ratio; n'envoyezresolutionque lorsque les détails du modèle l'exposent. Sur les modèles avec des niveaux de résolution, unesizede1K,2Kou4Kest envoyée en tant queresolution; un niveau différent deresolutionsera refusé. - L'image vers image Nano Banana doit être envoyée sur
/v1/images/generationsavecoperation: "image-to-image"et des URL d'images de référence. /v1/images/generationsn'accepte pasimages[]oufile_idau niveau racine ; ce sont des structures de flux d'édition.- Les références d'images distantes doivent être des URL
httpouhttpspubliques. N'envoyez pas d'URL de réseau privé, d'identifiants intégrés, de fragments d'URL ou d'URL signées qui pourraient expirer avant le début du traitement.
Exemple de texte vers 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": "A clean product photo of a ceramic coffee cup on a walnut desk",
"size": "1024x1024",
"response_format": "url"
}'Exemple d'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-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'Obtenir l'image
Les réponses d'image peuvent être synchrones ou asynchrones :
- Les réponses synchrones renvoient
data[]final avecurloub64_json. - Les réponses asynchrones renvoient
id,task_id,statuset généralementpoll_url. Envoyez"async": truesur un modèle qui prend en charge l'exécution asynchrone publique pour obtenir une tâche au lieu d'attendre l'image. - Pour vérifier une tâche asynchrone, appelez
GET /v1/tasks/{id}avec l'idoutask_idrenvoyé. - Utilisez une requête synchrone lorsque vous avez besoin de
b64_json; les résultats d'image asynchrones utilisent des URL.
Les URL des résultats d'image sont des URL de résultats multimédias TokenLab qui restent valides pendant 30 jours. media_retention.items signale le statut de sauvegarde de chaque élément et expires_at ; la réponse peut omettre media_retention lorsque le statut de sauvegarde n'est pas connu à temps, et l'URL fonctionne toujours. Les résultats Base64 en ligne sont en dehors de cette rétention de copie d'URL. Enregistrer manuellement une image dans la bibliothèque multimédia lui donne un cycle de vie distinct. Voir Rétention des données.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Conservez l'URL de l'image renvoyée, l'ID de tâche, le modèle et votre propre ID utilisateur/travail. Ne continuez pas à interroger après un statut terminal.
Avant le lancement
- Validez les entrées utilisateur avant d'appeler TokenLab : longueur du prompt, nombre d'images, accessibilité de l'URL et type de fichier.
- Définissez des délais d'attente HTTP suffisamment élevés pour les requêtes synchrones haute résolution. Utilisez
async: truelà où le modèle le prend en charge pour les travaux longs. - Stockez
request_id,task_id,poll_url, le modèle, l'endpoint et les noms de champs envoyés. - Lorsqu'une requête d'image renvoie une tâche, une
Idempotency-Keyrend la requête de création sûre à réessayer : après un délai d'attente du client, envoyez la même requête avec la même clé pour obtenir cette tâche. Pour une requête qui renvoie l'image directement, une nouvelle tentative avec la même clé peut renvoyer un statut de tâche au lieu de l'image, ou409avecidempotent_response_not_replayable. Sans clé, vérifiez si une tâche a été créée avant de réessayer. - Utilisez l'utilisation et
billing_transaction_idpour la facturation finale.
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 documenté pour ce modèle | Supprimez le champ ou choisissez un modèle/endpoint qui le documente |
Pas de b64_json sur résultat asynchrone | Les tâches d'image asynchrones renvoient des résultats orientés URL | Utilisez le mode synchrone pour une sortie base64 |
| Image de référence rejetée | Mauvais endpoint ou URL privée/expirée | Faites correspondre la forme de référence documentée du modèle et utilisez des URL accessibles |
Référence API
| Sujet | Référence |
|---|---|
| Créer une image | Créer une image |
| Modifier une image | Modifier 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 |