Édition multi-tour et retouches ciblées

Leçon réécrite le 3 novembre 2026 d’après la page Image Editing, l’Image Prompting Guide et la référence de l’API Images de xAI : l’endpoint /v1/images/edits n’a pas de paramètre mask — ni dans la référence, ni dans le SDK xai-sdk 1.21.0 —, contrairement à ce qu’affirmait l’ancienne version. Une retouche se cible par le prompt, et une zone se protège au pixel près par un masque appliqué chez vous, après l’édition. Sources : Image Editing · Image Prompting Guide · Images API.

Chaîner les éditions

L’édition d’images devient vraiment puissante lorsque vous enchaînez plusieurs modifications. Le principe, décrit par xAI, est simple : la sortie d’une édition devient l’entrée de la suivante, ce qui permet de partir d’une image de base puis d’ajouter des détails, d’ajuster le style ou de corriger, tour après tour.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

def edit_image(image_url, prompt):
    """Édite une image et retourne l'URL du résultat."""
    response = requests.post(
        "https://api.x.ai/v1/images/edits",
        headers=headers,
        json={
            "model": "grok-imagine-image",
            "prompt": prompt,
            "image": {"url": image_url}
        }
    )
    response.raise_for_status()
    return response.json()["data"][0]["url"]

# Tour 1 : modifier l'arrière-plan
url_tour1 = edit_image(
    "https://exemple.com/portrait.jpg",
    "Remplacez l'arrière-plan par un bureau moderne avec vue sur la ville. "
    "Gardez la même personne, la même pose et le même cadrage."
)

# Tour 2 : ajuster l'éclairage
url_tour2 = edit_image(
    url_tour1,
    "Rendez la lumière chaude et tamisée, comme en fin de journée. "
    "Gardez la même personne, le même décor et le même cadrage."
)

# Tour 3 : ajouter un élément
url_tour3 = edit_image(
    url_tour2,
    "Placez un ordinateur portable ouvert sur le bureau, devant la personne. "
    "Gardez la même personne, la même lumière et le même cadrage."
)

print(f"Résultat final : {url_tour3}")

Bonnes pratiques pour le multi-tour

Le guide de xAI conseille d’éditer quand le sujet et la mise en page sont déjà bons et qu’il reste un à trois détails à changer ; si le sujet lui-même est faux, mieux vaut régénérer. Chaque tour commence par la modification, puis fixe en une phrase ce qui ne bouge pas : le sujet, l’angle, le cadrage, la place des objets. Deux formulations échouent selon le guide : celle qui s’ouvre sur « garde tout », qui ne change presque rien, et celle qui recopie un prompt complet, qui recompose la scène — le sujet dérive, un objet se dédouble ou se change en un objet voisin.

Ordonnez les tours du général au particulier : le fond, la composition et l’ambiance d’abord, les accessoires et les corrections fines ensuite, pour qu’un grand changement tardif ne vienne pas défaire les petites retouches.

Deux réflexes de sécurité complètent la méthode. Téléchargez chaque résultat intermédiaire dès qu’il est produit : les URL sont temporaires, et perdre le tour 3 d’une série de cinq oblige à repartir du tour 2. Et inspectez chaque étape avant d’enchaîner : un défaut introduit au tour 1 — un doigt déformé, une ombre incohérente — se retrouve dans tous les tours suivants, puisque chacun part de l’image précédente.

Cibler une zone par le prompt

L’API ne prend pas de masque : c’est le prompt qui cible. Désignez la partie à modifier aussi précisément que possible — par son nom, sa position, sa matière — et nommez ce qui doit rester identique.

url_chapeau = edit_image(
    url_tour3,
    "Remplacez la casquette de la personne par un chapeau de paille à large bord. "
    "Gardez le même visage, la même coiffure, le même décor et le même cadrage."
)

Quand une correction ne prend pas, le guide recommande de changer de mots plutôt que de répéter la même demande, en désignant la partie de l’image à corriger et ce qu’elle doit montrer. Pour assembler plusieurs images — un produit dans un décor, un personnage d’une image à l’autre —, l’édition accepte jusqu’à cinq images sources (leçon 7).

Protéger une zone au pixel près : le masque local

Si une partie de l’image ne doit pas bouger d’un pixel — un logo, un visage, un texte —, appliquez le masque chez vous, après l’édition : vous gardez la zone d’origine et ne prenez de l’édition que ce qui se trouve hors de cette zone. Avec Pillow, Image.composite(image1, image2, masque) copie image1 là où le masque est blanc et garde image2 là où il est noir :

from PIL import Image, ImageDraw

original = Image.open("original.jpg").convert("RGB")
edite = Image.open("edite.jpg").convert("RGB").resize(original.size)

# Masque : blanc = prendre l'édition, noir = garder l'original
masque = Image.new("L", original.size, 255)
draw = ImageDraw.Draw(masque)
draw.rectangle([40, 40, 360, 160], fill=0)  # zone protégée, par exemple un logo

resultat = Image.composite(edite, original, masque)
resultat.save("resultat.jpg")

Les trois images doivent avoir la même taille. Le redimensionnement suppose que l’édition a gardé le ratio de la source : vérifiez-le, ou imposez-le avec le paramètre aspect_ratio de la requête. Le masque n’empêche pas le modèle de toucher à la zone ; il vous permet de la restaurer ensuite.

Pipeline d’édition complet

Voici un exemple de pipeline structuré, qui garde l’historique de chaque tour :

class ImageEditor:
    def __init__(self, api_key):
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        self.history = []

    def edit(self, image_url, prompt):
        response = requests.post(
            "https://api.x.ai/v1/images/edits",
            headers=self.headers,
            json={
                "model": "grok-imagine-image",
                "prompt": prompt,
                "image": {"url": image_url}
            }
        )
        response.raise_for_status()

        result_url = response.json()["data"][0]["url"]
        self.history.append({
            "prompt": prompt,
            "input": image_url,
            "output": result_url
        })
        return result_url

Points clés à retenir

• L’édition multi-tour chaîne les résultats : chaque sortie devient l’entrée de l’édition suivante
• Éditez quand le sujet et la mise en page sont bons et qu’il reste un à trois détails à changer
• Chaque tour : la modification d’abord, puis ce qui doit rester identique
• L’API n’a pas de paramètre mask : on cible par le prompt, et on protège une zone par un masque local appliqué après l’édition
• Les URL de sortie sont temporaires : téléchargez les résultats intermédiaires