Формати на изображения: URL и Base64
На тази страница
Обновено на 3 ноември 2026 г. С API за отговори (Responses API) обектите
input_imageиinput_textсе поставят в масиваcontentна съобщение с формат{"role": "user", ...}, а не директно вinput. Примерът с Python преди това извиквашеclient.responses.create()върху клиентаxai-sdk, който няма такъв метод, и записваше API ключа директно в кода: сега използва функциитеuser(...)иimage(...)от SDK, като ключът се чете от променливите на средата. Добавено е предупреждение от xAI относно съхранението на историята. Кодът е тестван сxai-sdkверсия 1.21.0. Източник: Image Understanding.
Изпращане на изображения към Grok
Моделите Grok от версия grok-4.5 нагоре включват възможности за компютърно зрение. Можете да изпратите едно или повече изображения във вашите API заявки и моделът ще ги анализира, за да отговори на въпросите ви. Това се нарича „разбиране на изображения“ или мултимодално зрение.
Преди да преминете към конкретни случаи на употреба, е от съществено значение да овладеете двата формата за подаване на изображения, поддържани от xAI API.
Директен URL
Най-простият метод е да предоставите публичния URL адрес на изображението. Моделът автоматично ще го изтегли и анализира.
С API за отговори (основна крайна точка):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Опишете подробно това изображение."
}
]
}
]
}
xAI препоръчва, когато изпращате изображения, да не съхранявате историята на заявките и отговорите на техните сървъри, в противен случай заявката може да се провали: при използване на API за отговори предайте "store": false.
С API за чат завършвания (Chat Completions API – остаряло, съвместимо с OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Опишете подробно това изображение."
}
]
}
]
}
URL адресът трябва да сочи към публично достъпен файл с изображение. Ако изображението е зад система за автентикация или защитен CDN, използвайте вместо това формата Base64.
Кодирани в Base64 (Data URI)
Вторият формат включва кодиране на самото изображение директно в заявката като низ в Base64, предшестван от MIME префикс. Това е идеалният метод, когато работите с локални изображения, екранни снимки или динамично генерирани файлове.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Префиксът data:image/jpeg;base64, информира модела за MIME типа на изображението. Коригирайте го според формата:
data:image/jpeg;base64,за файлове JPG/JPEGdata:image/png;base64,за файлове PNG
Кодиране на изображение в Python
import base64
with open("photo.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
image_url = f"data:image/jpeg;base64,{image_data}"
Кодиране в JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Основни разлики между URL и Base64
| Критерий | URL | Base64 |
|---|---|---|
| Размер на заявката | Лека (само URL адресът) | Тежка (+33% спрямо оригиналния файл) |
| Достъпност | Изисква се публично изображение | Работи с всеки локален файл |
| Латентност | Изтегляне от сървъра | Данните са директно в заявката |
| Типичен случай на употреба | Уеб изображения, CDN, облачно хранилище | Локални файлове, екранни снимки, качвания |
Смесване на текст и изображения
Полето content на едно съобщение приема смесен масив от обекти input_image и input_text във всякакъв ред: можете свободно да редувате текст и изображения. С родния xAI SDK същото съобщение се изгражда с user(), което приема текст и изображения, създадени чрез image() в последователност:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # ключът се чете от XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Сравнете тези две снимки:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Какви са основните разлики?",
)
)
response = chat.sample()
print(response.content)
Функцията image() приема публичен URL адрес или Data URI в Base64.
Ключови изводи
- Поддържат се два формата за изображения: Директен URL и Base64 (Data URI)
- Приетите формати са само JPG, JPEG и PNG
- Всяко изображение не трябва да надвишава 20 MiB
- Броят на изображенията на заявка е неограничен
- API за отговори поставя
input_imageвcontentна съобщението; Chat Completions използва частиimage_url; xAI SDK използваimage()вътре вuser() - Предпочитайте URL за публични изображения и Base64 за локални файлове