URL:er temporaires et stratégies de téléchargement
På denna sida
Leçon terminée le 3 novembre 2026 sur la base des pages Image Generation et Imagine outputs de xAI : le paramètre
storage_optionsconserve l’image dans l’API Files et peut générer une URL publique permanente ; la documentation ne précise pas la durée de vie des URL éphémères (les « erreurs 403 ou 404 » de la version précédente n’y figurent pas) ; les images sont produites en JPEG par défaut. Sources : Image Generation · Imagine outputs.
Gestion des images générées éphémères
Les URL renvoyées par l’API de génération et d’édition d’images sont temporaires : la documentation de xAI les décrit comme ayant une durée de vie courte sans en préciser la limite, et t’invite à télécharger ou traiter les images sans délai. Cette contrainte impacte directement la conception de tes applications.
Le problème des URL temporaires
Lorsque tu utilises response_format="url" (la valeur par défaut), l’API renvoie une URL éphémère. Après une période non spécifiée, elle cesse de servir l’image.
# URL éphémère : à télécharger sans délai
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape"
)
url = response.data[0].url
Conséquence : tu ne peux pas stocker ces URL dans une base de données pour les réutiliser plus tard. Tu dois systématiquement télécharger les images.
Stratégie 1 : Téléchargement immédiat
La stratégie la plus fiable consiste à télécharger chaque image dès sa génération :
import urllib.request
import os
from datetime import datetime
def generate_and_save(prompt, output_dir="images"):
"""Génère une image et l'enregistre immédiatement."""
os.makedirs(output_dir, exist_ok=True)
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filepath = os.path.join(output_dir, f"gen_{timestamp}.jpg") # JPEG par défaut
urllib.request.urlretrieve(response.data[0].url, filepath)
print(f"Image enregistrée : {filepath}")
return filepath
Stratégie 2 : Utilisation de Base64
En demandant la réponse en Base64, tu reçois directement les données binaires de l’image, sans dépendre d’une URL temporaire :
import base64
response = client.images.generate(
model="grok-imagine-image",
prompt="A mountain landscape",
response_format="b64_json"
)
# Les données sont directement dans la réponse
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("mountain.jpg", "wb") as f: # JPEG par défaut
f.write(image_bytes)
Avantages de Base64
L’avantage de Base64 tient en un mot : autonomie. L’image arrive directement dans la réponse JSON, sans dépendre d’une URL temporaire qui pourrait expirer avant que ton code ne la consomme, et sans requête HTTP supplémentaire pour la télécharger — un aller-retour réseau en moins signifie un point de défaillance en moins dans ton pipeline.
Inconvénients de Base64
La contrepartie est mécanique : l’encodage Base64 gonfle la réponse JSON d’environ 33 %, ce qui te coûte triple — en temps de transfert de la réponse API, en mémoire consommée côté client pour le décodage, et en complexité si tu manipules plusieurs images haute résolution dans la même requête. Pour une image unique, c’est négligeable ; pour un lot de dix images 2k, la différence devient tangible.
Stratégie 3 : Stockage cloud automatique
Pour les applications de production, combine la génération avec un upload vers ton stockage :
import boto3
import urllib.request
import tempfile
def generate_and_upload_s3(prompt, bucket, key):
"""Génère une image et l'upload directement sur S3."""
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
# Téléchargement vers un fichier temporaire
with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
urllib.request.urlretrieve(response.data[0].url, tmp.name)
# Upload vers S3
s3 = boto3.client("s3")
s3.upload_file(tmp.name, bucket, key)
permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
return permanent_url
Stratégie 4 : Laisser xAI stocker l’image
Chaque requête Imagine accepte un paramètre storage_options qui sauvegarde l’image produite dans l’API Files de ton équipe, et peut en outre créer une URL publique permanente, à partager ou intégrer. Avec le SDK xAI :
import os
import xai_sdk
client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client_xai.image.sample(
prompt="A mountain landscape at sunrise",
model="grok-imagine-image-2.0",
storage_options={"filename": "mountain.jpg", "public_url": True},
)
print(response.file_output.file_id) # identifiant stable dans l'API Files
print(response.public_url) # URL publique permanente
La réponse conserve l’URL éphémère habituelle et ajoute, pour chaque image, un bloc file_output : file_id, filename et, si demandé, public_url. Seul filename est requis : sans autres options, l’image est stockée en privé, sans expiration ni URL publique. expires_after (de 3 600 secondes à 30 jours) planifie la suppression du fichier, et public_url accepte aussi son propre expires_after, qui ne peut dépasser celui du fichier. Une équipe peut avoir jusqu’à 1 000 URL publiques actives ; au-delà, ou en cas d’incident, l’image reste stockée et la réponse porte un public_url_error au lieu de l’URL. Via REST, le même objet storage_options va dans le corps de la requête, y compris pour une édition.
Pipeline robuste avec nouvelle tentative
Les URL temporaires peuvent parfois échouer lors du téléchargement. Implémente un mécanisme de nouvelle tentative :
import time
import urllib.request
import urllib.error
def download_with_retry(url, filepath, max_retries=3):
"""Télécharge une image avec nouvelle tentative en cas d'erreur."""
for attempt in range(max_retries):
try:
urllib.request.urlretrieve(url, filepath)
return True
except urllib.error.URLError as e:
if attempt < max_retries - 1:
wait_time = 2 ** attempt # Backoff exponentiel
print(f"Tentative {attempt + 1} échouée, réessai dans {wait_time}s...")
time.sleep(wait_time)
else:
print(f"Échec après {max_retries} tentatives : {e}")
return False
Bonnes pratiques
Toute discipline découle d’un seul fait : les URL sont temporaires. Le téléchargement doit donc suivre immédiatement la génération, dans le même flux de code — chaque minute d’écart est une fenêtre où l’image peut devenir irrécupérable. Pour la même raison, une URL temporaire ne doit jamais être stockée dans une base de données comme référence permanente : elle sera morte à la prochaine consultation, et c’est le genre de bug qui n’apparaît qu’en production, plusieurs jours plus tard. Dans les applications critiques où la fiabilité prime, contourne le problème avec b64_json, qui livre l’image dans la réponse, ou avec storage_options, qui la conserve chez xAI avec un identifiant stable.
Le téléchargement lui-même mérite d’être traité comme une opération réseau normale : une nouvelle tentative avec backoff pour absorber les échecs transitoires, un nommage de fichier par horodatage ou identifiant unique pour éviter les collisions lorsque plusieurs générations s’exécutent en parallèle. Enfin, journalise les métadonnées — prompt, modèle, paramètres — avec chaque image enregistrée : six mois plus tard, quand tu devras régénérer un visuel « comme celui-là mais en 2k », ce journal sera inestimable.
Viktiga punkter
- Les URL de sortie sont temporaires : télécharge immédiatement
- Le format
b64_jsonévite le problème des URL éphémères - Base64 augmente la taille de la réponse d’environ 33 %
- Implémente une nouvelle tentative avec backoff exponentiel pour la robustesse
- En production, upload vers un stockage permanent (S3, GCS), ou fais stocker l’image par xAI avec
storage_options