Skip to main content
POST
POST /v1/images/edits L’endpoint image à image utilise un corps de Request multipart/form-data. Téléversez une ou plusieurs images de référence et envoyez les champs de prompt et de paramètres sous forme de champs de formulaire.
Utilisez https://bettertoken.ai/v1 comme Base URL. Passez votre BetterToken API Key via Authorization: Bearer YOUR_API_KEY.
Vous pouvez renseigner les champs de formulaire et téléverser des images de référence dans le Playground à droite de la page, puis envoyer la Request directement à https://bettertoken.ai/v1/images/edits.
N’utilisez pas de corps JSON ordinaire pour les Request image à image. Envoyez les champs texte et fichier avec multipart/form-data.

Valeurs recommandées

Envoyez explicitement ces champs dans chaque Request :
Utilisez image pour une seule image de référence. Utilisez des champs image[] répétés pour plusieurs images de référence.

Une image de référence

Plusieurs images de référence

Modifier une zone sélectionnée avec un masque

Ajoutez le champ de fichier facultatif mask pour orienter la modification vers une zone sélectionnée. Le point de terminaison BetterToken actuel lit un seul fichier dans mask. N’envoyez pas plusieurs champs mask[].
  • L’image d’origine et le masque doivent utiliser le même format et les mêmes dimensions en pixels. Chaque fichier doit faire moins de 50 MB. Pour une compatibilité maximale, utilisez un PNG avec canal Alpha pour les deux fichiers.
  • Le masque doit contenir un canal Alpha. Les pixels entièrement transparents (Alpha 0) indiquent la zone que le modèle peut redessiner. Les pixels entièrement opaques (Alpha 255) indiquent au modèle de préserver cette zone.
  • Une image RVB ordinaire en noir et blanc n’est pas un masque valide si elle ne contient pas réellement de canal Alpha.
  • Si vous envoyez plusieurs champs image[], le masque s’applique à la première image d’entrée.
  • Le masque guide le modèle. Il ne garantit pas que les pixels situés en dehors de la zone transparente resteront parfaitement identiques.

Édition avec masque en Python

Ouvrez les deux fichiers dans une seule instruction with afin que Python les ferme après la requête :

Vérifier les fichiers avant l’envoi

Cette vérification minimale avec Pillow contrôle les exigences de format, de dimensions et de canal Alpha. Pour un masque local classique, elle affiche aussi un avertissement si le canal Alpha ne contient pas à la fois des zones entièrement transparentes et opaques :

Exemple Python

Tailles recommandées

size représente le ratio attendu et le niveau de taille. Les pixels réellement renvoyés peuvent être mappés ou ajustés par le serveur. Utilisez les dimensions de l’image décodée plutôt que de recadrer de force la sortie à la valeur demandée.

Enregistrer l’image

Une réponse réussie suit la structure de réponse d’image OpenAI compatible :
Lisez data[0].b64_json et enregistrez-le comme contenu d’image base64. Définissez toujours output_format: "png" afin de pouvoir enregistrer l’image décodée sous .png.

Flux de réponse

Cet endpoint est synchrone. Après l’envoi de POST /images/edits, gardez la Request HTTP actuelle ouverte jusqu’à la réponse du serveur. Lorsque la génération réussit, le contenu de l’image est renvoyé dans data[0].b64_json. L’endpoint ne renvoie pas de task_id, et il n’existe pas d’endpoint distinct de requête de statut ou de téléchargement de résultat.

Documents associés

Autorisations

Authorization
string
header
requis

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corps

multipart/form-data
model
enum<string>
défaut:gpt-image-2
requis

Use the GPT Image 2 model ID.

Options disponibles:
gpt-image-2
Exemple:

"gpt-image-2"

prompt
string
requis

Instructions for editing the image or generating from reference images.

Exemple:

"Use this reference image to create a more polished square product hero image while preserving the main style."

image
file

The reference image field for a single input image.

image[]
file[]

Repeat this field for each input when sending multiple reference images.

mask
file

An optional single mask file. The mask and original image must have the same format and dimensions, each file must be smaller than 50 MB, and the mask must contain an Alpha channel. For maximum compatibility, use PNG with an Alpha channel for both files. With multiple image[] inputs, the mask applies to the first image.

n
défaut:1

Use 1. Send separate requests when you need multiple output images.

Exemple:

"1"

size
enum<string>
défaut:1024x1024

The requested image size or aspect-ratio tier. The server may map or adjust the final pixel dimensions, so inspect the decoded image for its actual size.

Options disponibles:
auto,
1024x1024,
1536x1024,
1024x1536,
1536x1152,
1152x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Exemple:

"1024x1024"

response_format
enum<string>
défaut:b64_json

Use b64_json.

Options disponibles:
b64_json
Exemple:

"b64_json"

output_format
enum<string>
défaut:png

Use png. Do not rely on jpeg or webp being returned directly in the selected format.

Options disponibles:
png
Exemple:

"png"

Réponse

Image editing result.

created
integer
Exemple:

1710000000

data
object[]