Премини към основното съдържание
Български— Изберете език
Меню

Източници на изображения: URL и Base64

Урок 6 от 14 Обновен 3 ноември 2026 г. Начинаещ
На тази страница
  1. Предоставяне на изображения на крайната точка за редактиране
  2. Формат на URL
  3. Формат на Base64 Data URI
  4. Трети вариант: Файл от Files API
  5. Помощна функция
  6. Практическо упражнение
  7. Ключови изводи

Обновено на 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 адресът трябва да бъде публично достъпен, за да работи