Sources d'images : URL et Base64

Fournir des images à l’endpoint d’édition

L’endpoint d’édition accepte les images sources dans deux formats : URL publique et Data URI Base64. Chaque format a ses avantages et ses cas d’usage spécifiques. Maîtriser les deux 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.

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 résultats sont identiques :

# 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

• Deux formats d’entrée : URL publique et Data URI Base64
• 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