Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Väliaikaiset URL-osoitteet ja latausstrategiat

Oppitunti 13 / 14 Päivitetty 3. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Väliaikaisten luotujen kuvien käsittely
  2. Ongelma väliaikaisten URL-osoitteiden kanssa
  3. Strategia 1: Välitön lataus
  4. Strategia 2: Base64:n käyttäminen
  5. Strategia 3: Automaattinen pilvitallennus
  6. Strategia 4: xAI:n kuvan tallennuksen hyödyntäminen
  7. Vankka putki uudelleenyrityksillä
  8. Parhaat käytännöt
  9. Keskeiset asiat

Oppitunti suoritettu 3. marraskuuta 2026 perustuen xAI:n Image Generation ja Imagine outputs -sivuihin: storage_options-parametri säilyttää kuvan Files API:ssa ja voi luoda pysyvän julkisen URL-osoitteen; dokumentaatio ei määrittele väliaikaisten URL-osoitteiden elinikää (edellisen version “403- tai 404-virheet” eivät esiinny tässä); kuvat tulostuvat oletusarvoisesti JPEG-muodossa. Lähteet: Image Generation · Imagine outputs.

Väliaikaisten luotujen kuvien käsittely

Kuvien luonti- ja muokkausrajapinnan palauttamat URL-osoitteet ovat väliaikaisia: xAI:n dokumentaatio kuvailee niitä lyhytikäisiksi määrittelemättä tarkkaa elinikää, ja kehottaa lataamaan tai käsittelemään kuvat viipymättä. Tämä rajoite vaikuttaa suoraan sovellustesi suunnitteluun.

Temp.
Output URLs
b64
Persistent Alternative
+33%
Base64 Size Overhead
30 days
xAI Storage, or unlimited

Ongelma väliaikaisten URL-osoitteiden kanssa

Kun käytät arvoa response_format="url" (oletus), rajapinta palauttaa väliaikaisen URL-osoitteen. Määrittämättömän ajan kuluttua se lakkaa tarjoamasta kuvaa.

# Väliaikainen URL: lataa viipymättä
response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape"
)

url = response.data[0].url

Seuraus: et voi tallentaa näitä URL-osoitteita tietokantaan ja käyttää niitä myöhemmin uudelleen. Sinun on järjestelmällisesti ladattava kuvat.

Strategia 1: Välitön lataus

Luotettavin strategia on ladata jokainen kuva heti sen luomisen jälkeen:

import urllib.request
import os
from datetime import datetime

def generate_and_save(prompt, output_dir="images"):
    """Luo kuvan ja tallentaa sen välittömästi."""
    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")  # Oletusarvoisesti JPEG

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

Strategia 2: Base64:n käyttäminen

Pyytämällä vastausta Base64-muodossa saat kuvan binääridatan suoraan ilman riippuvuutta väliaikaiseen URL-osoitteeseen:

import base64

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

# Data on suoraan vastauksessa
image_bytes = base64.b64decode(response.data[0].b64_json)

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

Base64:n edut

Base64:n etu tiivistyy yhteen sanaan: autonomia. Kuva saapuu suoraan JSON-vastauksessa ilman riippuvuutta väliaikaiseen URL-osoitteeseen, joka saattaa vanhentua ennen kuin koodisi ehtii käsitellä sen, ja ilman ylimääräistä HTTP-pyyntöä sen lataamiseen – yksi verkkopyyntö vähemmän tarkoittaa yhtä vikapistettä vähemmän putkessasi.

Base64:n haitat

Kompromissi on mekaaninen: Base64-koodaus kasvattaa JSON-vastausta noin 33 %, mikä maksaa sinulle kolminkertaisesti – API-vastauksen siirtoajassa, asiakkaan muistinkulutuksessa dekoodaukseen ja kompleksisuudessa, jos käsittelet useita korkean resoluution kuvia samassa pyynnössä. Yksittäisen kuvan kohdalla se on merkityksetöntä; kymmenen 2k-kuvan erässä ero tulee tuntuvaksi.

Strategia 3: Automaattinen pilvitallennus

Tuotantosovelluksissa yhdistä luonti lataukseen omaan tallennustilaasi:

import boto3
import urllib.request
import tempfile

def generate_and_upload_s3(prompt, bucket, key):
    """Luo kuvan ja lataa sen suoraan S3:een."""
    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    # Lataa väliaikaiseen tiedostoon
    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
        urllib.request.urlretrieve(response.data[0].url, tmp.name)

        # Lataa S3:een
        s3 = boto3.client("s3")
        s3.upload_file(tmp.name, bucket, key)

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

Strategia 4: xAI:n kuvan tallennuksen hyödyntäminen

Jokainen Imagine-pyyntö hyväksyy storage_options-parametrin, joka tallentaa tuotetun kuvan tiimisi Files API:hun ja voi lisäksi luoda pysyvän julkisen URL-osoitteen jakamista tai upottamista varten. xAI SDK:n kanssa:

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)  # Vakaa tunniste Files API:ssa
print(response.public_url)           # Pysyvä julkinen URL-osoite

Vastaus säilyttää tavanomaisen väliaikaisen URL-osoitteen ja lisää jokaiselle kuvalle file_output-lohkon: file_id, filename ja pyydettäessä public_url. Vain filename on pakollinen: ilman muita vaihtoehtoja kuva tallennetaan yksityisesti ilman vanhenemista tai julkista URL-osoitetta. expires_after (3 600 sekunnista 30 päivään) ajoittaa tiedoston poiston, ja public_url hyväksyy myös oman expires_after-arvonsa, joka ei voi ylittää tiedoston arvoa. Tiimillä voi olla enintään 1 000 aktiivista julkista URL-osoitetta; tämän ylittyessä tai häiriötilanteessa kuva säilyy silti tallennettuna, ja vastaus sisältää public_url_error URL-osoitteen sijaan. REST-rajapinnan kautta sama storage_options-objekti menee pyynnön runkoon, myös muokkauksen yhteydessä.

Vankka putki uudelleenyrityksillä

Väliaikaiset URL-osoitteet voivat joskus epäonnistua latauksen aikana. Toteuta uudelleenyritysmekanismi:

import time
import urllib.request
import urllib.error

def download_with_retry(url, filepath, max_retries=3):
    """Lataa kuvan uudelleenyrityksellä virhetilanteessa."""
    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  # Eksponentiaalinen viive
                print(f"Yritys {attempt + 1} epäonnistui, yritetään uudelleen {wait_time}s kuluttua...")
                time.sleep(wait_time)
            else:
                print(f"Epäonnistui {max_retries} yrityksen jälkeen: {e}")
                return False

Parhaat käytännöt

Kaikki kurinalaisuus kumpuaa yhdestä faktasta: URL-osoitteet ovat väliaikaisia. Latauksen on siis seurattava luontia välittömästi samassa koodivirrassa – jokainen minuutin aukko on ikkuna, jonka aikana kuva voi muuttua palautumattomaksi. Samasta syystä väliaikaista URL-osoitetta ei saa koskaan tallentaa tietokantaan pysyvänä viitteenä: se on kuollut seuraavaan hakuun mennessä, ja tämä on virhe, joka ilmenee vasta tuotannossa, päivien kuluttua. Kriittisissä sovelluksissa, joissa luotettavuus on etusijalla, ohita ongelma käyttämällä b64_json:ää, joka toimittaa kuvan vastauksessa, tai storage_options:ia, joka pitää kuvan xAI:ssa vakaalla tunnisteella.

Itse lataus ansaitsee kohtelun normaalina verkkotoimenpiteenä: uudelleenyritys viiveellä ohimenevien häiriöiden absorboimiseksi, tiedoston nimeäminen aikaleimalla tai yksilöllisellä tunnisteella törmäysten välttämiseksi, kun useita luonteja suoritetaan rinnakkain. Lopuksi, lokita metadata – kehote, malli, parametrit – jokaisen tallennetun kuvan yhteyteen: kuuden kuukauden kuluttua, kun tarvitset uudelleenluoda visuaalin “kuin tuo, mutta 2k:ssa”, tämä loki on korvaamaton.

Keskeiset asiat

  • Tulostus-URL-osoitteet ovat väliaikaisia: lataa välittömästi
  • b64_json-muoto välttää väliaikaisen URL-osoitteen ongelman
  • Base64 kasvattaa vastauksen kokoa noin 33 %
  • Toteuta uudelleenyritys eksponentiaalisella viiveellä luotettavuuden vuoksi
  • Tuotannossa lataa pysyvään tallennustilaan (S3, GCS) tai anna xAI:n tallentaa kuva käyttämällä storage_options:ia