Източници на изображения: URL и Base64
На тази страница
Обновено на 3 ноември 2026 г. Въз основа на страницата Image Editing и справочника за xAI Images API: изходното изображение може да се зададе и чрез
file_idна файл в Files API, като алтернатива наurl. Източници: Image Editing · Images API.
Предоставяне на изображения на крайната точка за редактиране
Крайната точка за редактиране приема изходни изображения в три формата: публичен URL, Base64 Data URI или file_id на файл, вече качен в xAI Files API. Всеки формат има своите случаи на употреба; овладяването им Ви позволява да изградите гъвкави процеси за редактиране.
Формат на URL
Форматът на URL е най-удобният вариант, стига изображението вече да е онлайн: няма нужда от кодиране, полезният товар е минимален, а заявката остава четима в дневниците. Ключовото ограничение тук е публичност – изображението трябва да бъде достъпно за сървърите на xAI без сесия или токен.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Ограничения на URL
- URL адресът трябва да бъде публично достъпен (без връзки, защитени с удостоверяване)
- Поддържаните формати са JPEG, PNG и WebP
- Изображението трябва да се зарежда бързо (избягвайте бавни сървъри)
Използване на изходни URL адреси от API
Това прави многократното редактиране практично: резултатът от една редакция става вход за следващата, без никога да сваляте изображението на локалната си машина. Има обаче едно предупреждение – тези URL адреси изтичат, така че веригата трябва да се изпълни наведнъж. За работен поток, разпределен във времето, сваляйте изображението между всяка стъпка.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Генериране на изображение
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"]
# Редактиране на генерираното изображение
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 Data URI
За изображения, съхранявани локално или генерирани динамично, използвайте формата Base64 Data URI:
import base64
# Четене на локално изображение
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
}
}
Кога да използвате Base64?
Критерият е прост: Base64 е необходим, когато използването на публичен URL би било излишно отклонение. Това важи за локални изображения, които не са хоствани никъде – качването им на сървър само за да станат достъпни за API, добавя стъпка и забавяне без стойност. Това важи и за изображения, генерирани в паметта от Вашето приложение: диаграма, създадена в реално време, екранна снимка на рендер или динамично композирана миниатюра никога не трябва да докосват диска. Base64 решава и проблем с поверителността – изображение, кодирано в тялото на заявката, никога не се излага на публичен сървър, дори временно – и опростява архитектурата: автоматизиран процес, свързващ генериране, редактиране и запазване, работи от край до край без междинно хостване, което да се осигурява, защитава и почиства.
Внимавайте с размера
Base64 увеличава полезния товар с около една трета, което е незначително за миниатюра, но става съществено за снимка с размер няколко мегабайта – по-дълго време за качване и риск от надвишаване на лимитите за размер на заявката. Правилото е следното: ако изображението вече е достъпно онлайн, използвайте URL; ако е локално, Base64 е по-прост от хостването му само за случая.
Трети вариант: Файл от Files API
Изображение, вече качено в xAI Files API, се задава чрез неговия идентификатор, вместо чрез URL. Двете полета се изключват взаимно: обектът image съдържа или url, или file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Това е естественият избор за изображение, използвано повторно при множество редакции: то се изпраща само веднъж и не трябва да бъде публично.
Помощна функция
Ето функция, която обработва автоматично двата формата:
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}")
Тази функция автоматично открива дали източникът е URL или път до локален файл и форматира обекта съответно.
Практическо упражнение
Тествайте двата формата с едно и също изображение и подкана, за да проверите дали и двата пътя работят; получените изображения ще варират от изпълнение до изпълнение, както при всяко генериране:
# Чрез URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Чрез Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Ключови изводи
- Три входни формата: публичен URL, Base64 Data URI или
file_idот Files API - Временните URL адреси, върнати от API, могат да служат като източници за редактиране
- Base64 увеличава размера на полезния товар с ~33%
- Създайте помощна функция за автоматично обработване на двата формата
- URL адресът трябва да бъде публично достъпен, за да работи