Endpoint /v1/images/edits : modifier vos images — Générer et éditer des images avec Grok

Mise à jour du 2 novembre 2026 — Imagine. grok-imagine-image-quality est retiré depuis le 2 novembre 2026 (ses requêtes sont servies par Imagine 2.0 en qualité low) : les exemples utilisent désormais grok-imagine-image (Imagine 1.0) et grok-imagine-image-2.0 (Imagine 2.0, qualité low, medium ou auto). Avec le SDK OpenAI, aspect_ratio, resolution et quality passent par extra_body, et l’édition passe par le SDK xAI ou une requête HTTP.

L’édition d’images avec l’API Grok

Au-delà de la génération, l’API xAI propose un endpoint dédié à l’édition d’images existantes : POST /v1/images/edits. Cet endpoint vous permet de modifier, transformer ou enrichir des images en décrivant les changements souhaités par un simple prompt textuel.

Images sources max

Formats d'entrée

JSON

Content-Type requis

∞

Tours d'édition

Structure d’une requête d’édition

L’édition fonctionne comme la génération à une différence près, qui change tout dans la façon de rédiger : 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 ; « ajoutez des lunettes de soleil » conserve la photo et n’intervient que sur ce point. C’est la confusion la plus fréquente au 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": "Ajoutez 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 au lieu du SDK OpenAI ?

Voici le piège technique de cette leçon, et il vaut mieux le connaître avant d’y passer une heure : la compatibilité avec le SDK OpenAI, qui fonctionne parfaitement pour la génération, s’arrête à l’édition. L’endpoint d’édition xAI utilise un format JSON, tandis que la méthode images.edit() du SDK envoie du multipart/form-data. Cette incompatibilité de content-type signifie que vous devez utiliser directement l’API REST avec la bibliothèque requests pour les éditions.

# NE FONCTIONNE PAS avec l'API xAI
# client.images.edit(...)  # Envoie en multipart, pas en JSON

# FONCTIONNE : appel REST direct
requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json=payload
)

Paramètres de l’endpoint d’édition

model (obligatoire) : grok-imagine-image (Imagine 1.0) ou grok-imagine-image-2.0 (Imagine 2.0, qui accepte aussi quality)
prompt (obligatoire) : description de la modification à apporter
image : objet contenant l’URL d’une seule image source
images : tableau d’objets pour plusieurs images sources (mutuellement exclusif avec image)
mask : objet contenant l’URL du masque de zone à éditer
n : nombre de variantes à générer (1 à 10)
response_format : url ou b64_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 et le changement d’ambiance fonctionnent très bien parce qu’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 prend tout son intérêt, en délimitant précisément la zone à recalculer.

Ajout d’éléments : “Ajoutez des lunettes de soleil au personnage”
Suppression : “Retirez l’arrière-plan et remplacez-le par un fond blanc”
Transformation de style : “Convertissez cette photo en illustration aquarelle”
Modification d’ambiance : “Changez la scène du jour à la nuit”
Correction : “Améliorez l’éclairage et augmentez le contraste”

# Exemple : changer le style d'une image
payload = {
    "model": "grok-imagine-image",
    "prompt": "Transformez cette photo en une illustration style bande dessinée franco-belge",
    "image": {
        "url": "https://exemple.com/photo-ville.jpg"
    }
}

Mise en pratique

Essayez d’éditer une image en plusieurs étapes. Commencez par une modification simple, puis affinez :

# Étape 1 : modifier l'arrière-plan
payload_step1 = {
    "model": "grok-imagine-image",
    "prompt": "Remplacez l'arrière-plan par un coucher de soleil sur la mer",
    "image": {"url": "https://exemple.com/portrait.jpg"}
}

Points clés à retenir

L’endpoint d’édition est POST /v1/images/edits
Utilisez requests en Python, pas le SDK OpenAI (incompatibilité de format)
Vous pouvez 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 l’édition ; avec le SDK OpenAI, images.edit() n’est pas pris en charge par xAI : passez par le SDK xAI ou une requête HTTP