Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

URL:er temporaires et stratégies de téléchargement

Lektion 13 av 14 Uppdaterad 3 november 2026 Nybörjare
På denna sida
  1. Gestion des images générées éphémères
  2. Le problème des URL temporaires
  3. Stratégie 1 : Téléchargement immédiat
  4. Stratégie 2 : Utilisation de Base64
  5. Stratégie 3 : Stockage cloud automatique
  6. Stratégie 4 : Laisser xAI stocker l’image
  7. Pipeline robuste avec nouvelle tentative
  8. Bonnes pratiques
  9. Viktiga punkter

Leçon terminée le 3 novembre 2026 sur la base des pages Image Generation et Imagine outputs de xAI : le paramètre storage_options conserve 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.

Temp.
URL de sortie
b64
Alternative persistante
+33 %
Surcoût de taille Base64
30 jours
Stockage xAI, ou illimité

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