Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Ajutised URL-id ja allalaadimisstrateegiad

Õppetund 13 / 14 Värskendatud 3. november 2026 Algajatele
Sellel lehel
  1. Ajutiste genereeritud piltide haldamine
  2. Probleem ajutiste URL-idega
  3. 1. strateegia: Viivitamatu allalaadimine
  4. 2. strateegia: Base64 kasutamine
  5. 3. strateegia: Automaatne pilvesalvestus
  6. 4. strateegia: Lase xAI-l pilti salvestada
  7. Tugev töövoog kordustega
  8. Parimad tavad
  9. Peamised punktid

Tund lõpetatud 3. novembril 2026, tuginedes xAI lehtedele Image Generation ja Imagine outputs: parameeter storage_options hoiab pildi Files API-s ja võib luua püsiva avaliku URL-i; dokumentatsioon ei täpsusta ajutiste URL-ide eluiga (eelnevas versioonis esinenud „403 või 404 veateated“ seal ei ilmu); väljundpildid on vaikimisi JPEG-vormingus. Allikad: Image Generation · Imagine outputs.

Ajutiste genereeritud piltide haldamine

Pildigeneratsiooni ja -töötluse API tagastatud URL-id on ajutised: xAI dokumentatsioon kirjeldab neid lühiajalistena, täpsustamata nende eluiga, ja palub sul pilte viivitamatult alla laadida või töödelda. See piirang mõjutab otseselt seda, kuidas sa oma rakendusi disainid.

Temp.
Väljund URL-id
b64
Püsiv alternatiiv
+33%
Base64 suuruse ülekulu
30 päeva
xAI salvestusruum või piiramatu

Probleem ajutiste URL-idega

Kui kasutad response_format="url" (vaikeseade), tagastab API ajutise URL-i. Määramata aja möödudes lõpetab see pildi teenindamise.

# Ajutine URL: laadi alla viivitamatult
response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape"
)

url = response.data[0].url

Tagajärg: sa ei saa neid URL-e andmebaasi salvestada ja hiljem uuesti kasutada. Sa pead pilte süstemaatiliselt alla laadima.

1. strateegia: Viivitamatu allalaadimine

Kõige usaldusväärsem strateegia on laadida iga pilt alla kohe pärast selle genereerimist:

import urllib.request
import os
from datetime import datetime

def generate_and_save(prompt, output_dir="images"):
    """Genereerib pildi ja salvestab selle kohe."""
    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")  # Vaikimisi JPEG

    urllib.request.urlretrieve(response.data[0].url, filepath)
    print(f"Pilt salvestatud: {filepath}")
    return filepath

2. strateegia: Base64 kasutamine

Kui taotled vastust Base64-vormingus, saad pildi binaarsed andmed otse kätte, ilma et peaksid tuginema ajutisele URL-ile:

import base64

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape",
    response_format="b64_json"
)

# Andmed on otse vastuses
image_bytes = base64.b64decode(response.data[0].b64_json)

with open("mountain.jpg", "wb") as f:  # Vaikimisi JPEG
    f.write(image_bytes)

Base64 eelised

Base64 eelis taandub ühele sõnale: autonoomia. Pilt saabub otse JSON-vastuses, ilma et peaksid tuginema ajutisele URL-ile, mis võib aeguda enne, kui su kood seda tarbib, ja ilma täiendava HTTP-päringuta selle allalaadimiseks – üks võrgutaotlus vähem tähendab ühte tõrkepunkti vähem sinu töövoos.

Base64 puudused

Kompromiss on mehaaniline: Base64 kodeering paisutab JSON-vastust umbes 33%, mis maksab sulle kolmekordselt – API vastuse edastusajas, kliendi mälus, mida kulutatakse selle dekodeerimiseks, ja keerukuses, kui manipuleerid sama päringuga mitme kõrge eraldusvõimega pildiga. Üksiku pildi puhul on see tühine; kümne 2k pildi partiis muutub erinevus käegakatsutavaks.

3. strateegia: Automaatne pilvesalvestus

Tootmisrakenduste jaoks kombineeri genereerimine üleslaadimisega oma salvestusruumi:

import boto3
import urllib.request
import tempfile

def generate_and_upload_s3(prompt, bucket, key):
    """Genereerib pildi ja laadib selle otse S3-i."""
    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    # Laadi alla ajutisse faili
    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
        urllib.request.urlretrieve(response.data[0].url, tmp.name)

        # Laadi üles S3-i
        s3 = boto3.client("s3")
        s3.upload_file(tmp.name, bucket, key)

    permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
    return permanent_url

4. strateegia: Lase xAI-l pilti salvestada

Iga Imagine päring aktsepteerib parameetrit storage_options, mis salvestab loodud pildi sinu meeskonna Files API-sse ja võib lisaks luua püsiva avaliku URL-i jagamiseks või manustamiseks. Kasutades xAI SDK-d:

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)  # Stabiilne identifikaator Files API-s
print(response.public_url)           # Püsiv avalik URL

Vastus säilitab tavapärase ajutise URL-i ja lisab iga pildi kohta ploki file_output: file_id, filename ja soovi korral public_url. Ainult filename on kohustuslik: muude valikute puudumisel salvestatakse pilt privaatselt, ilma aegumise või avaliku URL-ita. expires_after (3600 sekundist kuni 30 päevani) planeerib faili kustutamise ja public_url aktsepteerib samuti oma expires_after, mis ei tohi ületada faili oma. Meeskonnal võib olla kuni 1000 aktiivset avalikku URL-i; sellest üle minnes või intsidenti korral on pilt siiski salvestatud ja vastus sisaldab URL-i asemel public_url_error. REST-i kaudu läheb sama storage_options objekt päringu kehasse, kaasa arvatud redigeerimisel.

Tugev töövoog kordustega

Ajutised URL-id võivad allalaadimisel mõnikord nurjuda. Rakenda kordusmehhanism:

import time
import urllib.request
import urllib.error

def download_with_retry(url, filepath, max_retries=3):
    """Laadib pildi alla, tehes vea korral kordusi."""
    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  # Eksponentsiaalne tagasitõmbumine
                print(f"Katse {attempt + 1} ebaõnnestus, proovin uuesti {wait_time}s pärast...")
                time.sleep(wait_time)
            else:
                print(f"Ebaõnnestus pärast {max_retries} katset: {e}")
                return False

Parimad tavad

Kogu distsipliin tuleneb ühest faktist: URL-id on ajutised. Allalaadimine peab seetõttu järgnema genereerimisele viivitamatult, samas koodivoos – iga minutiline vahe on aken, mille jooksul võib pilt muutuda taastamatuks. Samal põhjusel ei tohi ajutist URL-i kunagi salvestada andmebaasi püsiva viitena: järgmiseks päringuks on see surnud ja see on viga, mis avaldub alles tootmises, päevi hiljem. Kriitilistes rakendustes, kus usaldusväärsus on esikohal, möödu probleemist, kasutades b64_json, mis edastab pildi vastuses, või storage_options, mis hoiab seda xAI juures stabiilse identifikaatoriga.

Allalaadimist ennast tuleb käsitleda kui tavalist võrgutoimingut: kordus eksponentsiaalse tagasitõmbumisega mööduvate tõrgete neelamiseks, failide nimetamine ajatempli või unikaalse identifikaatori järgi, et vältida kokkupõrkeid, kui mitu genereerimist jooksevad paralleelselt. Lõpuks logi metaandmed – viip, mudel, parameetrid – iga salvestatud pildi juurde: kuue kuu pärast, kui sul on vaja visuali uuesti genereerida „nagu see, aga 2k-s“, on see logi hindamatu.

Peamised punktid

  • Väljund URL-id on ajutised: laadi need kohe alla
  • Vorming b64_json väldib ajutise URL-i probleemi
  • Base64 suurendab vastuse suurust umbes 33%
  • Tugevuse tagamiseks rakenda kordus eksponentsiaalse tagasitõmbumisega
  • Tootmises laadi üles püsivasse salvestusruumi (S3, GCS) või lase xAI-l pilt parameetriga storage_options salvestada