Formaty obrazów: URL i Base64
Na tej stronie
Zaktualizowano 3 listopada 2026 r. W przypadku interfejsu API Responses obiekty
input_imageiinput_textumieszcza się w polucontentwiadomości{"role": "user", ...}, a nie bezpośrednio winput. Przykład w języku Python wcześniej wywoływałclient.responses.create()na klienciexai-sdk, który nie posiada tej metody, i zawierał klucz API w kodzie: teraz używa funkcjiuser(...)iimage(...)z SDK, a klucz jest odczytywany ze zmiennych środowiskowych. Dodano ostrzeżenie xAI dotyczące przechowywania historii. Kod zweryfikowany zxai-sdk1.21.0. Źródło: Image Understanding.
Wysyłanie obrazów do Grok
Modele Grok począwszy od wersji grok-4.5 obejmują możliwości widzenia komputerowego. Możesz wysłać jeden lub więcej obrazów w swoich żądaniach API, a model przeanalizuje je, aby odpowiedzieć na Twoje pytania. Nazywa się to rozumieniem obrazu lub wielomodalnym widzeniem.
Zanim przejdziesz do przypadków użycia, musisz opanować dwa formaty przesyłania obrazów obsługiwane przez API xAI.
Bezpośredni adres URL
Najprostszą metodą jest podanie publicznego adresu URL obrazu. Model automatycznie pobierze go i przeanalizuje.
W przypadku interfejsu API Responses (główny punkt końcowy):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Opisz szczegółowo ten obraz."
}
]
}
]
}
xAI zaleca, aby podczas wysyłania obrazów nie przechowywać historii żądań i odpowiedzi na swoich serwerach, w przeciwnym razie żądanie może się nie powieść: w przypadku interfejsu API Responses przekaż "store": false.
W przypadku interfejsu API Chat Completions (przestarzały, kompatybilny z OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Opisz szczegółowo ten obraz."
}
]
}
]
}
Adres URL musi wskazywać na publicznie dostępny plik obrazu. Jeśli obraz jest chroniony uwierzytelnianiem lub znajduje się za zabezpieczoną siecią CDN, użyj zamiast tego formatu Base64.
Kodowanie Base64 (Data URI)
Drugi format polega na zakodowaniu obrazu bezpośrednio w żądaniu jako ciąg Base64 poprzedzony prefiksem MIME. Jest to idealna metoda podczas pracy z obrazami lokalnymi, zrzutami ekranu lub plikami generowanymi dynamicznie.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Prefiks data:image/jpeg;base64, informuje model o typie MIME obrazu. Dostosuj go w zależności od formatu:
data:image/jpeg;base64,dla plików JPG/JPEGdata:image/png;base64,dla plików PNG
Kodowanie obrazu w języku 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}"
Kodowanie w JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Kluczowe różnice między URL a Base64
| Kryterium | URL | Base64 |
|---|---|---|
| Rozmiar żądania | Lekki (tylko adres URL) | Ciężki (+33% względem oryginalnego pliku) |
| Dostępność | Wymagany publiczny obraz | Działa z dowolnym plikiem lokalnym |
| Opóźnienie | Pobieranie przez serwer | Dane bezpośrednio w żądaniu |
| Typowy przypadek użycia | Obrazy sieciowe, CDN, magazyn w chmurze | Pliki lokalne, zrzuty ekranu, przesyłanie |
Łączenie tekstu i obrazów
Pole content wiadomości akceptuje mieszaną tablicę obiektów input_image i input_text w dowolnej kolejności: możesz swobodnie przeplatać tekst i obrazy. W natywnym SDK xAI tę samą wiadomość buduje się za pomocą user(), które akceptuje tekst i obrazy utworzone przez image() w sekwencji:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # klucz odczytany z XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Porównaj te dwa zdjęcia:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Jakie są główne różnice?",
)
)
response = chat.sample()
print(response.content)
Funkcja image() akceptuje publiczny adres URL lub identyfikator URI danych Base64.
Kluczowe wnioski
- Obsługiwane są dwa formaty obrazów: Bezpośredni URL i Base64 (Data URI)
- Akceptowane formaty to wyłącznie JPG, JPEG i PNG
- Każdy obraz nie może przekraczać 20 MiB
- Liczba obrazów na żądanie jest nieograniczona
- Interfejs API Responses umieszcza
input_imagew polucontentwiadomości; Chat Completions używa częściimage_url; SDK xAI używaimage()wewnątrzuser() - Preferuj URL dla obrazów publicznych, a Base64 dla plików lokalnych