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

Pildiallikad: URL ja Base64

Õppetund 6 / 14 Värskendatud 3. november 2026 Algajatele
Sellel lehel
  1. Piltide edastamine muutmise lõpppunkti
  2. URL-i formaat
  3. Base64 andme-URI formaat
  4. Kolmas variant: fail Files API-st
  5. Abifunktsioon
  6. Praktiline harjutus
  7. Peamised punktid

Uuendatud 3. novembril 2026. Lähtudes Pilditöötluse lehest ja xAI piltide API viitest: lähtepildi saab määrata ka Files API faili file_id abil, mis on url-i välistav alternatiiv. Allikad: Pilditöötlus · Piltide API.

Piltide edastamine muutmise lõpppunkti

Muutmise lõpppunkt (edit endpoint) aktsepteerib lähtepilte kolmel kujul: avalik URL, Base64 andme-URI või xAI Files API-sse juba üles laaditud faili file_id. Igal neist on oma kasutusvaldkond; nende valdamine võimaldab sul luua paindlikke töötlemise ahelaid.

URL-i formaat

URL-i formaat on kõige mugavam variant, kui pilt on juba veebis: midagi pole vaja kodeerida, kasutajaandmemaht on väike ja päring jääb logides loetavaks. Siinne peamine tingimus on avalikkus – pilt peab olema xAI serveritele kättesaadav ilma sessiooni või tokenita.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a gold frame around this image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

URL-i piirangud

  • URL peab olema avalikult ligipääsetav (autentimisega kaitstud lingid ei sobi)
  • Toetatud formaadid on JPEG, PNG ja WebP
  • Pilt peab olema kiiresti kättesaadav (välti aeglasi servereid)

API väljund-URL-ide kasutamine

See on see, mis teeb mitmeastmelise töötlemise praktiliseks: ühe muudatuse väljund saab järgmise sisendiks, ilma et peaks pilti oma kohalikku masinasse alla laadima. Üks aga – need URL-id aeguvad, seega peab ahel käivituma ühe hooga. Ajaliselt hajutatud töövoogu korraldades laadi see iga sammu vahel alla.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

# Pildi genereerimine
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "A medieval castle on a hill"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Genereeritud pildi muutmine
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Add a dragon flying over the castle",
        "image": {"url": generated_url}
    }
).json()

Base64 andme-URI formaat

Kohalikele või dünaamiliselt genereeritud piltidele kasuta Base64 andme-URI formaati:

import base64

# Kohaliku pildi lugemine
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transform this photo into a vector illustration",
    "image": {
        "url": data_uri
    }
}

Millal kasutada Base64-t?

Kriteerium on lihtne: Base64 on vajalik alati, kui avaliku URL-i kasutamine oleks asjatu ringtee. See kehtib kohalike piltide kohta, mida kusagil majutatud pole – nende serverisse laadimine, et muuta need API-le kättesaadavaks, lisab sammu ja viivitust ilma väärtuseta. See kehtib ka rakenduse mälus genereeritud piltide kohta: lennult loodud diagramm, renderduse ekraanitõmmis või dünaamiliselt koostatud pisipilt ei pea kunagi ketast puudutama. Base64 lahendab ka privaatsusmure – päringu kehas kodeeritud pilti ei avaldata kunagi avalikus serveris, isegi mitte ajutiselt – ja lihtsustab arhitektuuri: automatiseeritud torustik, mis aheldab genereerimise, muutmise ja salvestamise, töötab otsast otsani ilma vahepealse majutuseta, mida tuleks hallata, turvata ja puhastada.

Jälgi suurust

Base64 suurendab kasutajaandmemahtu umbes kolmandiku võrra, mis on pisipildi puhul tühine, kuid muutub mitme megabaidi suuruse foto puhul oluliseks – pikemad üleslaadimisajad ja oht ületada päringu suuruse piiranguid. Reegel on lihtne: kui pilt on juba veebis kättesaadav, kasuta URL-i; kui see on kohalik, on Base64 lihtsam kui selle ajutine majutamine.

Kolmas variant: fail Files API-st

Pilti, mis on juba xAI Files API-sse üles laaditud, määratakse selle identifikaatoriga, mitte URL-iga. Need kaks välja välistavad teineteist: image objekt sisaldab kas url või file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"file_id": "file_abc123"}
}

See on loomulik valik pildi jaoks, mida kasutatakse mitmes muudatuses: seda saadetakse ainult üks kord ja see ei pea olema avalik.

Abifunktsioon

Siin on funktsioon, mis haldab mõlemat formaati automaatselt:

import base64
import os

def prepare_image_source(source):
    """Prepares an image source for the API (URL or local file)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Invalid source: {source}")

See funktsioon tuvastab automaatselt, kas allikas on URL või kohaliku faili tee, ja vormindab objekti vastavalt.

Praktiline harjutus

Testi mõlemat formaati sama pildi ja vihjega, et veenduda mõlema tee toimimises; tulemuspildid erinevad käivituste lõikes nagu iga genereerimise puhul:

# URL-i kaudu
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Base64 kaudu
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": prepare_image_source("paysage.jpg")
}

Peamised punktid

  • Kolm sisendvormi: avalik URL, Base64 andme-URI või file_id Files API-st
  • API tagastatud ajutisi URL-e saab kasutada muutmise allikatena
  • Base64 suurendab kasutajaandmemahtu ~33%
  • Loo abifunktsioon mõlema formaadi automaatseks haldamiseks
  • URL peab toimimiseks olema avalikult ligipääsetav