TokenLab
Obtenir une clé API
DocumentationRéférence APIIntégrations

Images

Modifier une image

Modifier une image à partir d'une consigne et d'une image source

POST
/v1/images/edits

Aperçu

Crée une image modifiée ou étendue à partir d'une image originale et d'une consigne (prompt).

Cet endpoint prend en charge à la fois :

  • le flux de téléchargement multipart/form-data compatible avec OpenAI documenté ci-dessous
  • les requêtes JSON qui fournissent image_url, image_urls ou des références images officielles pour les familles image-à-image prises en charge

gpt-image-2 est pris en charge ici. Il accepte les téléchargements image en multipart, les image_url / image_urls en JSON, et les références images[] officielles (image_url ou file_id), avec jusqu'à 16 images sources. Créez d'abord les valeurs file_id via /v1/files. Définissez async: true pour renvoyer d'abord une tâche ; les modèles d'édition officiels FLUX/BFL utilisent également le même flux de polling de tâche.

Les éditions gpt-image-2 n'acceptent pas resolution ; utilisez size pour les dimensions de sortie. background accepte auto ou opaque ; transparent n'est pas pris en charge. Pour les éditions multi-images ou à haute latence, préférez async: true et interrogez (poll) la tâche renvoyée.

Les requêtes d'image de référence Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite et nano-banana-pro) sont exposées sur /v1/images/generations avec operation: "image-to-image" et image_urls, et non sur cet endpoint /v1/images/edits. Les requêtes d'édition d'image pour nano-banana-2, nano-banana-2.1, nano-banana-2-lite et nano-banana-pro utilisent également /v1/images/generations, avec operation: "image-edit".

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image et gemini-3-pro-image utilisent cet endpoint pour l'édition d'image. Leurs requêtes image-à-image utilisent /v1/images/generations avec operation: "image-to-image".

Les modèles d'édition d'image xAI Grok Imagine acceptent un nombre limité d'images sources : au maximum 5 pour grok-imagine-image-2.0, au maximum 3 pour grok-imagine-image et l'ancien grok-imagine-image-pro. Les requêtes avec plus d'images sources que le modèle n'en accepte échouent à la validation d'entrée avec 400 too_many_images.

input_fidelity ne fait pas partie des champs actuellement pris en charge par TokenLab pour gpt-image-2 ; omettez-le, sinon la requête renverra 400 unsupported_parameter.

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 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 ou plus, réglez donc le délai d'expiration de votre client HTTP sur au moins 120s. Si la réponse de création inclut status: "pending", task_id ou poll_url, suivez le poll_url renvoyé à la place.

URLs d'images distantes : lorsqu'une entrée multipart est nécessaire, TokenLab récupère image_url, image_urls ou images[].image_url en JSON et envoie les octets sous forme de parties image multipart. Les URLs doivent être des http/https publics, sans identifiants ou fragments intégrés, et ne doivent pas pointer vers localhost, des adresses IP privées ou réservées ; chaque redirection est vérifiée à nouveau. La charge utile récupérée doit être une image PNG, JPEG ou WebP réelle. Les limites sont de 50 MiB par image, 200 MiB au total pour les images récupérées par URL dans une seule requête, 30s de délai d'expiration pour la récupération, et jusqu'à 3 redirections.

Pour les requêtes JSON, fournissez exactement l'un des éléments suivants : image_url, image_urls ou images. Chaque objet images[] doit contenir exactement l'un des éléments suivants : image_url ou file_id. La limite globale de 200 MiB inclut toutes les images sources et le masque.

imagefile

Images sources multipart. Répétez image pour fournir plusieurs sources GPT Image. Les fichiers doivent être au format PNG, JPEG ou WebP, jusqu'à 16 images sources et 50 MiB chacune. Les modèles d'édition xAI Grok Imagine utilisent les mêmes champs d'entrée mais limitent les images sources : au maximum 5 pour grok-imagine-image-2.0 et 3 pour les autres modèles d'édition xAI.

promptstringrequis

Une description textuelle de l'édition souhaitée.

maskfile | object

Une image supplémentaire dont les zones entièrement transparentes indiquent où l'image doit être modifiée. Doit être un fichier PNG valide, de moins de 50 MiB, et avoir les mêmes dimensions que image.

Pour les requêtes JSON, mask peut également être un objet contenant exactement l'un des éléments suivants : image_url ou file_id ; les valeurs file_id doivent provenir de /v1/files et rester liées à la même configuration d'édition d'image.

modelstringrequis

Le modèle à utiliser pour les éditions d'image. Utilisez gpt-image-2 pour les éditions GPT Image, ou un autre modèle d'édition d'image actuel renvoyé par GET /v1/models?recommended_for=image.

nintegerpar défaut: 1

Nombre d'images à générer (1-10, dépend du modèle).

sizestring

La taille de l'image générée. Pour gpt-image-2, utilisez auto ou WIDTHxHEIGHT ; les dimensions doivent être des multiples de 16, le bord le plus long au maximum de 3840px, le rapport long/court au maximum de 3:1, et le nombre total de pixels entre 655 360 et 8 294 400.

Pour gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image et gemini-3.1-flash-lite-image, size accepte une taille de sortie issue de la table de tailles du modèle ou un niveau de résolution : 1K, 2K ou 4K. TokenLab envoie un niveau sous forme de resolution. Un niveau non pris en charge par le modèle, ou un niveau différent de resolution, renvoie 400 avec le code invalid_image_size_contract. La forme recommandée est aspect_ratio avec resolution.

response_formatstring

Comment les images sont renvoyées : url ou b64_json.

  • Omis : lorsque le modèle renvoie des octets d'image, chaque image se trouve dans data[].b64_json, et également dans data[].url lorsque TokenLab l'a stockée. Lorsque le modèle renvoie un lien, chaque image se trouve dans data[].url.
  • url : chaque image se trouve uniquement dans data[].url.
  • b64_json : chaque image se trouve uniquement dans data[].b64_json sous forme de données Base64.

Les liens sont des URLs de résultats média TokenLab. Ils restent valides pendant 30 jours. Voir Rétention des données.

asyncbooleanpar défaut: false

Définissez sur true avec gpt-image-2 ou les modèles d'édition officiels FLUX/BFL pour renvoyer une tâche avant que l'image finale ne soit prête. Les éditions asynchrones terminées renvoient des URLs indépendamment du response_format demandé ; utilisez des requêtes synchrones lorsque vous avez besoin de b64_json.

userstring

Un identifiant unique représentant votre utilisateur final pour la surveillance des abus.

Réponse

createdinteger

Horodatage Unix de la création des images.

dataarray

Tableau des images générées.

Chaque objet contient :

  • url (string) : URL de résultat média TokenLab de l'image éditée, valide pendant 30 jours. Absent lorsque response_format est b64_json. Lorsque response_format est omis, il est absent si TokenLab n'a pas pu stocker l'image.
  • b64_json (string) : Données d'image Base64. Présent lorsque response_format est b64_json, ou lorsqu'il est omis et que le modèle renvoie des octets d'image.

Réponse de tâche asynchrone

Définissez async: true avec gpt-image-2 ou les modèles d'édition officiels FLUX/BFL pour créer une tâche au lieu d'attendre l'image éditée dans la requête. 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'édition asynchrones renvoient uniquement les URLs des images finales. Si vous avez besoin de données d'image brutes 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 à l'utilisation réelle, et les tâches ayant échoué ou ayant expiré sont libérées ou remboursées.

Requête

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

Réponse

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Notes

Les échecs de récupération d'image distante sont renvoyés en tant qu'erreurs d'entrée avant le début de la génération. Les URLs inaccessibles, les délais d'expiration, les réponses 403/404, les hôtes privés/internes, les identifiants ou fragments dans l'URL, le contenu non-image, les formats non pris en charge et les violations de limite de taille renvoient 400 ou 413 et identifient l'entrée image_url / image_urls[n]. Pour les ressources privées ou protégées par des en-têtes, téléchargez directement les fichiers image multipart ou créez des références /v1/files.

Hy Image 3.5 Preview crée des images carrées de 1024 pixels à partir de texte et modifie des images de référence en utilisant des instructions écrites. Il est utile pour esquisser des visuels et affiner une composition.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

Autorisation

BearerAuth
AuthorizationBearer <token>

Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.

Emplacement: header

En-têtes

X-TokenLab-Delivery-Policy?string

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"

Corps de la requête

Réponse

application/json

application/json

application/json

application/json

application/json

application/json

Créer une image

Précédent

Créer une variation d'image

Suivant