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

Le format le plus simple consiste à fournir l’URL publiquement accessible d’une image :

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

Les images générées ou éditées par l’API retournent des URL temporaires que vous pouvez réutiliser comme sources pour une nouvelle édition :

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 ?

• Vous travaillez avec des images locales qui ne sont pas hébergées en ligne
• Vous traitez des images générées en mémoire par votre application
• Vous souhaitez éviter d’exposer vos images sur un serveur public
• Vous construisez un pipeline automatisé sans hébergement intermédiaire

Attention à la taille

Les images en Base64 augmentent la taille du payload de ~33%. Pour des images volumineuses, préférez les URL quand c’est possible.

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