Endpoint /v1/images/edits : modifier vos images
På denna sida
Mis à jour le 2 novembre 2026 — Imagine.
grok-imagine-image-qualitya été supprimé le 2 novembre 2026 (ses requêtes sont désormais traitées par Imagine 2.0 en qualitélow) : les exemples utilisent maintenantgrok-imagine-image(Imagine 1.0) etgrok-imagine-image-2.0(Imagine 2.0, qualitélow,mediumouauto). Avec le SDK OpenAI,aspect_ratio,resolutionetqualitypassent parextra_body, tandis que la modification d’image nécessite le SDK xAI ou une requête HTTP directe.
Modification d’images avec l’API Grok
Au-delà de la génération, l’API xAI propose un endpoint dédié pour modifier des images existantes : POST /v1/images/edits. Cet endpoint te permet de transformer, retoucher ou améliorer des images en décrivant les changements souhaités dans un simple prompt textuel.
Structure d’une requête de modification
La modification fonctionne comme la génération, avec une différence fondamentale qui change tout dans la façon d’écrire tes prompts : le prompt décrit la modification, pas l’image finale. « Une femme avec des lunettes de soleil » régénère une image entière ; « ajoute des lunettes de soleil » conserve la photo et n’intervient que sur ce point précis. C’est la confusion la plus fréquente lors du premier essai, et elle explique la plupart des résultats décevants.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Ajoute un chapeau rouge au personnage",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
Pourquoi utiliser requests plutôt que le SDK OpenAI ?
Voici le piège technique de cette leçon, et tu voudras le connaître avant d’y perdre une heure : la compatibilité avec le SDK OpenAI, qui fonctionne parfaitement pour la génération, s’arrête à la modification. L’endpoint de modification xAI utilise un format JSON, tandis que la méthode images.edit() du SDK envoie du multipart/form-data. Cette incompatibilité de type de contenu signifie que tu dois utiliser l’API REST directement avec la bibliothèque requests pour les modifications.
# NE FONCTIONNE PAS avec l'API xAI
# client.images.edit(...) # Envoie du multipart, pas du JSON
# FONCTIONNE : appel REST direct
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Paramètres de l’endpoint de modification
model(requis) :grok-imagine-image(Imagine 1.0) ougrok-imagine-image-2.0(Imagine 2.0, qui accepte aussiquality)prompt(requis) : description de la modification à appliquerimage: objet contenant l’URL d’une seule image sourceimages: tableau d’objets pour plusieurs images sources (exclusif avecimage)mask: objet contenant l’URL du masque de zone à modifiern: nombre de variantes à générer (1 à 10)response_format:urloub64_json
Types de modifications possibles
Les cinq familles ci-dessous n’ont pas le même taux de réussite, et il est utile de le savoir avant de promettre un résultat. L’ajout d’éléments et le changement d’ambiance fonctionnent très bien car ils s’appuient sur le contenu existant. La suppression est plus délicate : le modèle doit reconstruire ce qui se trouvait derrière l’élément retiré, et c’est là que le masque devient essentiel, en délimitant précisément la zone à recalculer.
- Ajout d’éléments : « Ajoute des lunettes de soleil au personnage »
- Suppression : « Supprime l’arrière-plan et remplace-le par un fond blanc »
- Transformation de style : « Convertis cette photo en illustration aquarelle »
- Modification d’ambiance : « Change la scène du jour à la nuit »
- Correction : « Améliore l’éclairage et augmente le contraste »
# Exemple : changer le style d'une image
payload = {
"model": "grok-imagine-image",
"prompt": "Transforme cette photo en illustration style bande dessinée franco-belge",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Mise en pratique
Essaie de modifier une image en plusieurs étapes. Commence par une modification simple, puis affine :
# Étape 1 : modifier l'arrière-plan
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Remplace l'arrière-plan par un coucher de soleil sur l'océan",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Viktiga punkter
- L’endpoint de modification est
POST /v1/images/edits - Utilise
requestsen Python, pas le SDK OpenAI (incompatibilité de format) - Tu peux fournir jusqu’à 5 images sources par requête
- Le prompt décrit la modification souhaitée en langage naturel
- Les deux modèles (Imagine 1.0 et Imagine 2.0) sont disponibles pour la modification ; avec le SDK OpenAI,
images.edit()n’est pas pris en charge par xAI : utilise le SDK xAI ou une requête HTTP