Tijdelijke URL's en downloadstrategieën
Op deze pagina
Les voltooid op 3 november 2026 op basis van de pagina’s Image Generation en Imagine outputs van xAI: de parameter
storage_optionsbewaart de afbeelding in de Files API en kan een permanente openbare URL genereren; de documentatie specificeert de levensduur van ephemere URL’s niet (de “403- of 404-fouten” uit de vorige versie komen hier niet voor); uitvoerafbeeldingen zijn standaard JPEG. Bronnen: Image Generation · Imagine outputs.
Omgaan met tijdelijk gegenereerde afbeeldingen
URL’s die door de API voor het genereren en bewerken van afbeeldingen worden teruggegeven, zijn tijdelijk: de documentatie van xAI beschrijft ze als kortstondig zonder de exacte levensduur te specificeren, en verzoekt u de afbeeldingen zonder uitstel te downloaden of te verwerken. Deze beperking heeft directe gevolgen voor het ontwerp van uw applicaties.
Het probleem met tijdelijke URL’s
Wanneer u response_format="url" gebruikt (de standaardwaarde), retourneert de API een ephemere URL. Na een niet-gespecificeerde periode stopt deze met het serveren van de afbeelding.
# Ephemere URL: direct downloaden
response = client.images.generate(
model="grok-imagine-image",
prompt="Een berglandschap"
)
url = response.data[0].url
Gevolg: u kunt deze URL’s niet in een database opslaan om ze later opnieuw te gebruiken. U moet de afbeeldingen systematisch downloaden.
Strategie 1: Direct downloaden
De meest betrouwbare strategie is om elke afbeelding direct na het genereren te downloaden:
import urllib.request
import os
from datetime import datetime
def generate_and_save(prompt, output_dir="images"):
"""Genereert een afbeelding en slaat deze direct op."""
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") # Standaard JPEG
urllib.request.urlretrieve(response.data[0].url, filepath)
print(f"Afbeelding opgeslagen: {filepath}")
return filepath
Strategie 2: Gebruikmaken van Base64
Door de respons in Base64 aan te vragen, ontvangt u de binaire gegevens van de afbeelding direct, zonder afhankelijk te zijn van een tijdelijke URL:
import base64
response = client.images.generate(
model="grok-imagine-image",
prompt="Een berglandschap",
response_format="b64_json"
)
# De gegevens staan direct in de respons
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("mountain.jpg", "wb") as f: # Standaard JPEG
f.write(image_bytes)
Voordelen van Base64
Het voordeel van Base64 komt neer op één woord: autonomie. De afbeelding arriveert direct in de JSON-respons, zonder afhankelijk te zijn van een tijdelijke URL die zou kunnen verlopen voordat uw code deze verwerkt, en zonder een extra HTTP-verzoek om deze te downloaden. Eén netwerkrondgang minder betekent één faalpunt minder in uw pipeline.
Nadelen van Base64
De keerzijde is mechanisch: Base64-codering blaast de JSON-respons op met ongeveer 33%, wat u drievoudig kost: in overdrachtstijd van de API-respons, in geheugen dat de client verbruikt om deze te decoderen, en in complexiteit als u meerdere afbeeldingen met hoge resolutie in hetzelfde verzoek manipuleert. Voor een eenmalige afbeelding is dit verwaarloosbaar; voor een batch van tien 2k-afbeeldingen wordt het verschil voelbaar.
Strategie 3: Automatische cloudopslag
Voor productieapplicaties combineert u generatie met een upload naar uw eigen opslag:
import boto3
import urllib.request
import tempfile
def generate_and_upload_s3(prompt, bucket, key):
"""Genereert een afbeelding en uploadt deze direct naar S3."""
response = client.images.generate(
model="grok-imagine-image",
prompt=prompt
)
# Downloaden naar een tijdelijk bestand
with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
urllib.request.urlretrieve(response.data[0].url, tmp.name)
# Uploaden naar S3
s3 = boto3.client("s3")
s3.upload_file(tmp.name, bucket, key)
permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
return permanent_url
Strategie 4: xAI de afbeelding laten opslaan
Elk Imagine-verzoek accepteert een parameter storage_options die de geproduceerde afbeelding opslaat in de Files API van uw team, en aanvullend een permanente openbare URL kan creëren om te delen of in te sluiten. Met de xAI SDK:
import os
import xai_sdk
client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client_xai.image.sample(
prompt="Een berglandschap bij zonsopgang",
model="grok-imagine-image-2.0",
storage_options={"filename": "mountain.jpg", "public_url": True},
)
print(response.file_output.file_id) # stabiele identifier in de Files API
print(response.public_url) # permanente openbare URL
De respons behoudt de gebruikelijke ephemere URL en voegt voor elke afbeelding een file_output-blok toe: file_id, filename en, indien gevraagd, public_url. Alleen filename is verplicht: zonder andere opties wordt de afbeelding privé opgeslagen, zonder vervaldatum of openbare URL. expires_after (van 3.600 seconden tot 30 dagen) plant het verwijderen van het bestand, en public_url accepteert ook zijn eigen expires_after, die de levensduur van het bestand niet mag overschrijden. Een team kan maximaal 1.000 actieve openbare URL’s hebben; daarboven, of in geval van een incident, wordt de afbeelding nog steeds opgeslagen en bevat de respons een public_url_error in plaats van de URL. Via REST gaat hetzelfde storage_options-object in de request body, ook voor een bewerking.
Robuuste pipeline met retry
Tijdelijke URL’s kunnen soms falen tijdens het downloaden. Implementeer een retry-mechanisme:
import time
import urllib.request
import urllib.error
def download_with_retry(url, filepath, max_retries=3):
"""Downloadt een afbeelding met retry bij fouten."""
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 # Exponentiële backoff
print(f"Poging {attempt + 1} mislukt, opnieuw proberen in {wait_time}s...")
time.sleep(wait_time)
else:
print(f"Mislukt na {max_retries} pogingen: {e}")
return False
Best practices
Alle discipline vloeit voort uit één feit: URL’s zijn tijdelijk. Downloaden moet daarom direct na generatie plaatsvinden, in dezelfde codeflow; elke minuut vertraging is een venster waarin de afbeelding onherroepelijk verloren kan gaan. Om dezelfde reden mag een tijdelijke URL nooit als permanente referentie in een database worden opgeslagen: deze zal bij de volgende opvraging dood zijn, en dit is het soort bug dat pas in productie opduikt, dagen later. In kritieke applicaties waar betrouwbaarheid voorop staat, omzeilt u het probleem met b64_json, dat de afbeelding in de respons levert, of met storage_options, dat deze bij xAI houdt met een stabiele identifier.
Het downloaden zelf verdient behandeling als een normale netwerkoperatie: een retry met backoff om tijdelijke storingen op te vangen, bestandsnamen op basis van timestamp of unieke identifier om botsingen te voorkomen wanneer meerdere generaties parallel draaien. Log tot slot metadata—prompt, model, parameters—bij elke opgeslagen afbeelding: over zes maanden, wanneer u een visueel moet regenereren “zoals die ene, maar dan in 2k”, is dit log onbetaalbaar.
Belangrijkste punten
- Output-URL’s zijn tijdelijk: download direct
- Het formaat
b64_jsonvermijdt het probleem van de ephemere URL - Base64 vergroot de responsgrootte met ~33%
- Implementeer een retry met exponentiële backoff voor robuustheid
- Upload in productie naar permanente opslag (S3, GCS), of laat xAI de afbeelding opslaan met
storage_options