TokenLab

Images

Modifier une image

Modifier une image à partir d'un prompt 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'un prompt.

Cet endpoint prend en charge à la fois :

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

gpt-image-2 est pris en charge ici. Il accepte les téléversements image en multipart, les image_url / image_urls en JSON, ainsi que les références images[] officielles (image_url ou file_id), avec jusqu'à 16 images sources. Créez d'abord des valeurs file_id via /v1/files. Définissez async: true pour renvoyer d'abord une tâche ; chaque modèle qui liste async parmi ses paramètres pris en charge, comme gpt-image-2 et les modèles d'édition FLUX, utilise le même flux de polling de tâche.

Les modifications avec 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 modifications multi-images ou à latence élevée, privilégiez async: true et interrogez la tâche renvoyée.

Les requêtes avec 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-to-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 : grok-imagine-image-2.0 en accepte au maximum 5, et grok-imagine-image en accepte au maximum 3. Les requêtes comportant plus d'images sources que le modèle n'en accepte échouent à la validation des entrées avec 400 too_many_images. Leurs requêtes image-to-image utilisent également cet endpoint.

Les détails de chaque modèle (GET /v1/models/{model}, voir Obtenir le modèle) indiquent l'endpoint pour chaque opération dans tokenlab.request_format_summary.request_endpoint_by_operation, ainsi que les champs acceptés et les limites dans tokenlab.request_format_details.operation_constraints. Une opération envoyée au mauvais endpoint renvoie 400 unsupported_endpoint.

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

Corps de la requête

Délai d'attente de requête synchrone : Certaines requêtes d'image renvoient l'image finale directement (inline) et attendent la fin de la génération. Les requêtes en haute résolution ou de haute qualité peuvent prendre près d'une minute ou plus ; configurez 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, interrogez plutôt GET /v1/tasks/{task_id}.

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

Pour les requêtes JSON, fournissez exactement l'un des paramètres image_url, image_urls ou images. Chaque objet images[] doit contenir exactement l'un des champs image_url ou file_id. La limite cumulée de 200 MiB comprend 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 le nombre d'images sources : au maximum 5 pour grok-imagine-image-2.0 et au maximum 3 pour les autres modèles d'édition xAI.

promptstringrequis

Une description textuelle de la modification souhaitée, jusqu'à 32 000 caractères. Requis pour chaque modèle dont les détails listent prompt. Les outils sans prompt, tels que stability-upscale-fast, sont appelés sans prompt.

maskfile | object

Une image supplémentaire dont les zones entièrement transparentes indiquent l'endroit 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 comportant exactement l'un des champs image_url ou file_id ; les valeurs file_id doivent provenir de /v1/files et rester associées à la même configuration d'édition d'image.

modelstringrequis

Le modèle à utiliser pour les modifications d'image. Utilisez gpt-image-2 pour les modifications 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, selon le 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 côté le plus long d'au maximum 3840px, le ratio longueur/largeur d'au maximum 3:1, et le nombre total de pixels compris 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 du tableau des tailles du modèle ou un palier de résolution : 1K, 2K ou 4K. TokenLab envoie un palier sous forme de resolution. Un palier non pris en charge par le modèle, ou un palier différent de resolution, renvoie 400 avec le code invalid_image_size_contract. Le format recommandé est aspect_ratio avec resolution.

response_formatstring

Format de retour des images : 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 URL de résultats multimédias TokenLab. Ils restent valides pendant 30 jours. Voir Rétention des données.

asyncbooleanpar défaut: false

Définissez sur true pour renvoyer une tâche avant que l'image finale ne soit prête. Seuls les modèles listant async parmi leurs paramètres pris en charge l'acceptent, par exemple gpt-image-2 ; pour tout autre modèle, la requête renvoie 400 unsupported_async_mode. Les modifications asynchrones terminées renvoient des URL quel que soit le 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 du moment où les images ont été créées.

dataarray

Tableau des images générées.

Chaque objet contient :

  • url (string) : URL de résultat multimédia TokenLab de l'image modifiée, valide pendant 30 jours. Non présente lorsque response_format est b64_json. Lorsque response_format est omis, elle est absente si TokenLab n'a pas pu stocker l'image.
  • b64_json (string) : Données d'image en Base64. Présente lorsque response_format est b64_json, ou lorsqu'il est omis et que le modèle renvoie des octets d'image.
usageobject

Nombre de tokens (input_tokens, output_tokens, total_tokens et leurs détails) pour les modèles tarifiés au token tels que gpt-image-2, lorsqu'ils sont disponibles.

Réponse de tâche asynchrone

Définissez async: true sur un modèle pris en charge pour créer une tâche au lieu d'attendre l'image modifiée dans la requête. La réponse comprend 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 des URL d'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 selon l'utilisation réelle, et les tâches ayant échoué ou 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://..."
    }
  ]
}

Remarques

Les échecs de récupération d'images distantes sont renvoyés sous forme d'erreurs d'entrée avant le début de la génération. Les URL inaccessibles, les délais dépassés, les réponses 403/404, les hôtes privés/internes, les identifiants ou fragments dans l'URL, le contenu non graphique, les formats non pris en charge et les dépassements de limite de taille renvoient 400 ou 413 et identifient l'entrée image_url / image_urls[n]. Le code est invalid_image_url, unsupported_image_content_type, too_many_images ou, avec 413, image_too_large ou image_input_too_large. Pour les ressources privées ou protégées par des en-têtes, téléversez directement les fichiers image multipart ou créez des références /v1/files.

Envoyez un en-tête Idempotency-Key pour réessayer une requête en toute sécurité après un délai d'attente ; voir Réessayer en toute sécurité avec une clé d'idempotence.

Hy Image 3.5 Preview modifie une image de référence à partir d'une instruction écrite. Il accepte uniquement size 1024x1024 et n 1 :

{
  "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"
Idempotency-Key?string

Clé optionnelle qui permet de réessayer une requête d'image en toute sécurité si la requête a créé une tâche. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque requête. Une tentative avec la même clé et le même corps renvoie alors cette tâche et ne crée, ne distribue ni ne facture une seconde tâche. Pour une requête qui renvoie l'image directement, une 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. Un corps différent avec une clé déjà acceptée est rejeté ; le code de statut et le code d'erreur pour ce cas ne sont pas garantis. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.

Longueur1 <= length <= 255

Corps de la requête

Réponse

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json