Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Šaltiniai vaizdams: URL ir Base64

Paskaita 6 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Pradedantisiems
Šiame puslapyje
  1. Vaizdų pateikimas redagavimo galiniam taškui
  2. URL formatas
  3. Base64 duomenų URI formatas
  4. Trečias variantas: failas iš Files API
  5. Pagalbinė funkcija
  6. Praktinė užduotis
  7. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d. Remiantis Vaizdų redagavimo puslapiu ir xAI vaizdų API nuoroda: šaltinio vaizdą taip pat galima nurodyti naudojant failo, esančio Files API, file_id kaip išskirtinę alternatyvą url. Šaltiniai: Vaizdų redagavimas · Vaizdų API.

Vaizdų pateikimas redagavimo galiniam taškui

Redagavimo galinis taškas priima šaltinio vaizdus trimis formomis: viešą URL, Base64 duomenų URI arba jau į xAI Files API įkeltos failo file_id. Kiekviena iš jų turi savo panaudojimo atvejus; jas įvaldęs galėsi kurti lanksčias redagavimo grandines.

URL formatas

URL formatas yra patogiausias pasirinkimas, jei vaizdas jau yra internete: nieko nereikia koduoti, naudingasis krūvis mažas, o užklausa išlieka skaitoma žurnaluose. Pagrindinis čia apribojimas – viešumas: vaizdą xAI serveriai turi galėti atsisiųsti be sesijos ar prieigos rakto.

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

URL apribojimai

  • URL turi būti viešai pasiekiamas (jokių nuorodų, apsaugotų autentifikavimu)
  • Palaikomi formatai: JPEG, PNG ir WebP
  • Vaizdas turi būti greitai pasiekiamas (venk lėtų serverių)

API grąžinamų išvesties URL naudojimas

Būtent tai daro daugkartinį redagavimą praktišku: vieno redagavimo išvestis tampa kito įvestimi, niekada neatsisiunčiant vaizdo į vietinį kompiuterį. Tačiau yra vienas niuansas – šie URL galioja ribotą laiką, todėl grandinė turi būti vykdoma vienu ypu. Jei darbo eiga išsibarsto laike, atsisiųsk vaizdą tarp kiekvieno žingsnio.

import requests
import os

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

# Sugeneruoti vaizdą
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"]

# Redaguoti sugeneruotą vaizdą
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 duomenų URI formatas

Vietiniams arba dinamiškai sugeneruotiems vaizdams naudok Base64 duomenų URI formatą:

import base64

# Nuskaityti vietinį vaizdą
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
    }
}

Kada naudoti Base64?

Kriterijus paprastas: Base64 būtinas tada, kai viešo URL naudojimas būtų nereikalingas nukeliavimas. Tai taikoma vietiniams vaizdams, kurie niekur nėra talpinami – jų įkėlimas į serverį tik tam, kad API galėtų juos pasiekti, pridėtų žingsnį ir delsą be jokios vertės. Tai taip pat taikoma atmintyje sugeneruotiems vaizdams: realiuoju laiku sukurtai diagramai, atvaizdavimo ekrano kopijai arba dinamiškai sudarytai miniatiūrai niekada nereikia liesti disko. Base64 taip pat sprendžia privatumo problemą – užklausos kūne koduotas vaizdas niekada nėra eksponuojamas viešame serveryje, net ir laikinai – bei supaprastina architektūrą: automatizuota grandinė, jungianti generavimą, redagavimą ir saugojimą, veikia nuo pradžios iki galo be tarpinio talpinimo, kurį reikėtų diegti, apsaugoti ir valyti.

Stebėk dydį

Base64 padidina naudingąjį krūvį maždaug trečdaliu; miniatiūrai tai nereikšminga, tačiau daugiamegabaitinei nuotraukai tai tampa reikšminga – ilgesnis įkėlimo laikas ir rizika viršyti užklausos dydžio ribas. Taisyklė paprasta: jei vaizdas jau pasiekiamas internete, naudok URL; jei jis vietinis, Base64 yra paprasčiau nei jį talpinti tik šiam kartui.

Trečias variantas: failas iš Files API

Vaizdas, jau įkeltas į xAI Files API, nurodomas jo identifikatoriumi vietoj URL. Abu laukai yra mutuariai eksklusyvūs: image objektas turi arba url, arba file_id.

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

Tai natūralus pasirinkimas vaizdui, naudojamam per kelis redagavimus: jis siunčiamas tik vieną kartą ir neturi būti viešas.

Pagalbinė funkcija

Štai funkcija, kuri automatiškai tvarko abu formatus:

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}")

Ši funkcija automatiškai aptinka, ar šaltinis yra URL, ar vietinio failo kelias, ir atitinkamai suformuoja objektą.

Praktinė užduotis

Išbandyk abu formatus su tuo pačiu vaizdu ir raginimu, kad įsitikintum, jog abu keliai veikia; gauti vaizdai kiekvieno vykdymo metu skirsis, kaip ir bet kurio generavimo atveju:

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

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

Svarbiausi punktai

  • Trys įvesties formos: viešas URL, Base64 duomenų URI arba file_id iš Files API
  • Laikini API grąžinti URL gali tarnauti kaip redagavimo šaltiniai
  • Base64 padidina naudingąjį krūvį ~33 %
  • Sukurk pagalbinę funkciją, kuri automatiškai tvarkytų abu formatus
  • URL turi būti viešai pasiekiamas, kad veiktų