Endpoint /v1/images/edits : modifier vos images

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.

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 ou grok-imagine-image-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 (standard et pro) sont disponibles pour l’édition