TokenLab

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 besoinEndpointÀ utiliser quandÀ éviter pour
Texte vers imagePOST /v1/images/generationsL'utilisateur commence uniquement avec du texteModifier un fichier image GPT existant
Image vers imagePOST /v1/images/generationsLe modèle accepte operation: "image-to-image" et des URL d'imagesModèles nécessitant une entrée d'édition multipart
Édition d'imagePOST /v1/images/editsUn modèle d'édition pris en charge modifie une image existanteGénération de référence de style Nano Banana
VariationPOST /v1/images/variationsUne intégration existante utilise déjà l'API de variationsUne nouvelle fonctionnalité d'image de référence
StatutGET /v1/tasks/{id}Une réponse de création renvoie task_id, status: "pending" ou poll_urlLa 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-image ou image-edit.
  • L'endpoint de requête attendu par le modèle.
  • Comment envoyer des références : image_url, image_urls, reference_image_urls, image en multipart, ou images[] en JSON.
  • Si le modèle accepte size, aspect_ratio, resolution, quality, background, output_format ou response_format.

Champs spécifiques au modèle

  • Les requêtes de style gpt-image-2 utilisent des champs size, quality et d'édition similaires à ceux d'OpenAI. Pour la génération et les modifications avec ce modèle, background accepte auto ou opaque ; transparent n'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'envoyez resolution que lorsque les détails du modèle l'exposent. Sur les modèles avec des niveaux de résolution, une size de 1K, 2K ou 4K est envoyée en tant que resolution ; un niveau différent de resolution sera refusé.
  • L'image vers image Nano Banana doit être envoyée sur /v1/images/generations avec operation: "image-to-image" et des URL d'images de référence.
  • /v1/images/generations n'accepte pas images[] ou file_id au niveau racine ; ce sont des structures de flux d'édition.
  • Les références d'images distantes doivent être des URL http ou https publiques. 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 avec url ou b64_json.
  • Les réponses asynchrones renvoient id, task_id, status et généralement poll_url. Envoyez "async": true sur 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' id ou task_id renvoyé.
  • 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: true là 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-Key rend 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, ou 409 avec idempotent_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_id pour la facturation finale.

Erreurs courantes

SymptômeCause probableSolution
400 avec param: "model"Modèle explicite manquantInterrogez /v1/models?recommended_for=image et envoyez model
Champ non pris en chargeLe champ n'est pas documenté pour ce modèleSupprimez le champ ou choisissez un modèle/endpoint qui le documente
Pas de b64_json sur résultat asynchroneLes tâches d'image asynchrones renvoient des résultats orientés URLUtilisez le mode synchrone pour une sortie base64
Image de référence rejetéeMauvais endpoint ou URL privée/expiréeFaites correspondre la forme de référence documentée du modèle et utilisez des URL accessibles

Référence API

SujetRéférence
Créer une imageCréer une image
Modifier une imageModifier une image
Créer une variation d'imageCréer une variation d'image
Obtenir le statut de l'imageObtenir le statut de l'image
Obtenir le statut de la tâcheObtenir le statut de la tâche

Sur cette page