Point de terminaison /v1/images/edits : Modifiez vos images
Ar an leathanach seo
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 l’édition nécessite le SDK xAI ou une requête HTTP directe.
Édition d’images avec l’API Grok
Au-delà de la génération, l’API xAI propose un point de terminaison dédié à la modification d’images existantes : POST /v1/images/edits. Ce point de terminaison te permet de modifier, transformer ou améliorer des images en décrivant les changements souhaités dans une simple invite textuelle.
Structure d’une requête d’édition
L’édition fonctionne comme la génération, avec une différence fondamentale qui change tout dans la façon dont tu rédiges tes invites : l’invite décrit la modification, et non 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 courante 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": "Add a red hat to the character",
"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 à l’édition. Le point de terminaison d’édition xAI utilise un format JSON, tandis que la méthode images.edit() du SDK envoie des données en 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 éditions.
# 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 du point de terminaison d’édition
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 à éditern: 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": "Transform this photo into a Franco-Belgian comic book style illustration",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Mise en pratique
Essaie d’éditer 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": "Replace the background with a sunset over the ocean",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Príomhphointí
- Le point de terminaison d’édition 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
- L’invite décrit la modification souhaitée en langage naturel
- Les deux modèles (Imagine 1.0 et Imagine 2.0) sont disponibles pour l’édition ; avec le SDK OpenAI,
images.edit()n’est pas pris en charge par xAI : utilise le SDK xAI ou une requête HTTP