Sources d'image : URL et Base64
På denna sida
Mis à jour le 3 novembre 2026. Basé sur la page Image Editing et la référence de l’API Images de xAI : une image source peut également être spécifiée en utilisant le
file_idd’un fichier présent dans l’API Files, comme alternative exclusive àurl. Sources : Image Editing · Images API.
Fournir des images au point de terminaison d’édition
Le point de terminaison d’édition accepte les images sources sous trois formes : une URL publique, un URI de données Base64 ou le file_id d’un fichier déjà téléchargé vers l’API Files de xAI. Chacune a ses cas d’usage ; les maîtriser te permet de construire des pipelines d’édition flexibles.
Format URL
Le format URL est l’option la plus pratique tant que l’image est déjà en ligne : rien à encoder, une charge utile minuscule et une requête qui reste lisible dans les journaux. La contrainte clé ici est publique : l’image doit être récupérable par les serveurs de xAI sans session ni jeton.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Contraintes de l’URL
- L’URL doit être accessible publiquement (pas de liens protégés par authentification)
- Les formats pris en charge sont JPEG, PNG et WebP
- L’image doit être accessible rapidement (évite les serveurs lents)
Utiliser les URL de sortie de l’API
C’est ce qui rend l’édition en plusieurs passes pratique : la sortie d’une édition devient l’entrée de la suivante, sans jamais télécharger l’image sur ta machine locale. Une mise en garde toutefois : ces URL expirent, donc la chaîne doit s’exécuter d’un seul tenant. Pour un flux de travail étalé dans le temps, télécharge-la 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": "A medieval castle on a hill"
}
).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": "Add a dragon flying over the castle",
"image": {"url": generated_url}
}
).json()
Format URI de données Base64
Pour les images stockées localement ou générées dynamiquement, utilise le format URI de données 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": "Transform this photo into a vector illustration",
"image": {
"url": data_uri
}
}
Quand utiliser Base64 ?
Le critère est simple : Base64 est nécessaire chaque fois qu’utiliser une URL publique constituerait un détour inutile. Cela s’applique aux images locales qui ne sont hébergées nulle part : les télécharger sur un serveur juste pour les rendre accessibles à l’API ajoute une étape et un délai sans valeur. Cela s’applique aussi aux images générées en mémoire par ton application : un graphique produit à la volée, une capture d’écran d’un rendu ou une vignette composée dynamiquement n’ont jamais besoin de toucher le disque. Base64 répond aussi à un souci 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 simplifie l’architecture : un pipeline automatisé enchaînant génération, édition et sauvegarde fonctionne de bout en bout sans hébergement intermédiaire à provisionner, sécuriser et nettoyer.
Surveille la taille
Base64 gonfle la charge utile d’environ un tiers, ce qui est négligeable pour une vignette mais devient significatif pour une photo de plusieurs mégaoctets : temps de téléchargement plus longs et risque de dépasser les limites de taille de requête. La règle empirique : si l’image est déjà accessible en ligne, utilise l’URL ; si elle est locale, Base64 est plus simple que de l’héberger juste pour l’occasion.
Troisième option : un fichier de l’API Files
Une image déjà téléchargée vers l’API Files de xAI est spécifiée par son identifiant, au lieu d’une URL. Les deux champs sont mutuellement exclusifs : un objet image contient soit url, soit file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
C’est le choix naturel pour une image réutilisée dans plusieurs éditions : elle n’est envoyée qu’une seule fois et n’a pas besoin d’être publique.
Fonction utilitaire
Voici une fonction qui gère automatiquement les deux formats :
import base64
import os
def prepare_image_source(source):
"""Prepares an image source for the API (URL or local file)."""
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"Invalid source: {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
Teste les deux formats avec la même image et la même invite pour vérifier que les deux chemins fonctionnent ; les images résultantes varieront d’une exécution à l’autre, comme toute génération :
# Via URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Via Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Viktiga punkter
- Trois formes d’entrée : URL publique, URI de données Base64 ou
file_idde l’API Files - Les URL temporaires renvoyées par l’API peuvent servir de sources d’édition
- Base64 augmente la taille de la charge utile d’environ 33 %
- Crée une fonction utilitaire pour gérer automatiquement les deux formats
- L’URL doit être accessible publiquement pour fonctionner