Šaltiniai vaizdams: URL ir Base64
Šiame puslapyje
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_idkaip 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_idiš 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ų