Sources d'images : URL et Base64 — Générer et éditer des images avec Grok

Leçon complétée le 3 novembre 2026 d’après la page Image Editing et la référence de l’API Images de xAI : une image source peut aussi être désignée par le file_id d’un fichier de la Files API, en alternative exclusive à url. Sources : Image Editing · Images API.

Fournir des images à l’endpoint d’édition

L’endpoint d’édition accepte les images sources sous trois formes : une URL publique, une Data URI Base64, ou l’identifiant file_id d’un fichier déjà téléversé dans la Files API de xAI. Chacune a ses cas d’usage ; les maîtriser vous permet de construire des pipelines d’édition flexibles.

Format URL

L’URL est le format le plus commode dès lors que l’image est déjà en ligne : rien à encoder, un payload minuscule, et une requête lisible dans les journaux. Le mot qui porte toute la contrainte est publiquement — l’image doit être récupérable par les serveurs de xAI, sans session ni jeton.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Ajoutez un cadre doré autour de cette image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

Contraintes des URL

L’URL doit être publiquement accessible (pas de lien protégé par authentification)
Les formats supportés sont JPEG, PNG et WebP
L’image doit être accessible rapidement (évitez les serveurs lents)

Utiliser les URL de sortie de l’API

C’est ce qui rend l’édition en plusieurs passes praticable : la sortie d’une édition devient l’entrée de la suivante, sans jamais rapatrier l’image chez vous. Une réserve toutefois — ces URL expirent, donc la chaîne doit s’exécuter d’un trait. Pour un enchaînement étalé dans le temps, téléchargez entre chaque étape.

import requests
import os

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

# Générer une image
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Un château médiéval sur une colline"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Éditer l'image générée
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Ajoutez un dragon survolant le château",
        "image": {"url": generated_url}
    }
).json()

Format Base64 Data URI

Pour les images stockées localement ou générées dynamiquement, utilisez le format Data URI Base64 :

import base64

# Lire une image locale
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transformez cette photo en illustration vectorielle",
    "image": {
        "url": data_uri
    }
}

Quand utiliser Base64 ?

Le critère est simple : Base64 s’impose chaque fois que passer par une URL publique serait un détour artificiel. C’est le cas des images locales qui ne sont hébergées nulle part — les téléverser sur un serveur juste pour les rendre accessibles à l’API ajouterait une étape et un délai sans aucune valeur. C’est aussi le cas des images générées en mémoire par votre application : un graphique produit à la volée, une capture d’écran d’un rendu, une vignette composée dynamiquement n’ont pas vocation à toucher le disque. Le Base64 répond enfin à une préoccupation de confidentialité — une image encodée dans le corps de la requête n’est jamais exposée sur un serveur public, même temporairement — et de simplicité d’architecture : un pipeline automatisé qui enchaîne génération, édition et sauvegarde fonctionne de bout en bout sans hébergement intermédiaire à provisionner, sécuriser et nettoyer.

Attention à la taille

Le Base64 gonfle le payload d’environ un tiers, ce qui est sans conséquence sur une vignette et devient sensible sur une photo de plusieurs mégaoctets — temps d’envoi allongé, et risque de dépasser les limites de taille de requête. La règle pratique : si l’image est déjà accessible en ligne, passez par l’URL ; si elle est locale, le Base64 reste plus simple que de l’héberger pour l’occasion.

Troisième voie : un fichier de la Files API

Une image déjà téléversée dans la Files API de xAI se désigne par son identifiant, à la place de l’URL. Les deux champs s’excluent : un objet image porte soit url, soit file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Ajoutez de la neige sur le paysage",
    "image": {"file_id": "file_abc123"}
}

C’est la voie naturelle pour une image réutilisée dans plusieurs éditions : elle n’est envoyée qu’une fois, et elle n’a pas à être publique.

Fonction utilitaire

Voici une fonction qui gère les deux formats automatiquement :

import base64
import os

def prepare_image_source(source):
    """Prépare une source d'image pour l'API (URL ou fichier local)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Source invalide : {source}")

Cette fonction détecte automatiquement si la source est une URL ou un chemin de fichier local et formate l’objet en conséquence.

Mise en pratique

Testez les deux formats avec la même image et le même prompt pour vérifier que les deux chemins aboutissent ; les images produites, elles, varieront d’un essai à l’autre, comme toute génération :

# Via URL
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Ajoutez de la neige sur le paysage",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Via Base64
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Ajoutez de la neige sur le paysage",
    "image": prepare_image_source("paysage.jpg")
}

Points clés à retenir

Trois formes d’entrée : URL publique, Data URI Base64 ou file_id de la Files API
Les URL temporaires retournées par l’API peuvent servir de sources d’édition
Le Base64 augmente la taille du payload de ~33%
Créez une fonction utilitaire pour gérer les deux formats automatiquement
L’URL doit être publiquement accessible pour fonctionner