Format treści: prosty ciąg znaków i tablica obiektów
Na tej stronie
Dwa formaty pola content
Pole content każdej wiadomości akceptuje dwa różne formaty w API Chat Completions od xAI. Wybór zależy od tego, co wysyłasz do modelu: zwykły tekst czy treść multimodalną (tekst + obrazy).
Format ciągu znaków: najczęstszy przypadek
W przypadku wiadomości zawierających wyłącznie tekst, pole content jest prostym ciągiem znaków:
{
"role": "user",
"content": "Wyjaśnij, jak działa transformer."
}
To format, którego będziesz używać w zdecydowanej większości przypadków. Jest prosty, czytelny i wystarczający do wszystkich interakcji tekstowych z Grok.
Dla wiadomości system niemal zawsze stosuje się format ciągu znaków:
{
"role": "system",
"content": "Jesteś ekspertem od architektury oprogramowania. Odpowiadaj po angielsku, podając przykłady kodu w Pythonie."
}
Format tablicy: treść multimodalna
Gdy musisz wysłać obrazy wraz z tekstem, pole content staje się tablicą typowanych obiektów. Każdy obiekt posiada pole type wskazujące jego rodzaj.
{
"role": "user",
"content": [
{
"type": "text",
"text": "Co przedstawia ten obraz?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Dostępne typy obiektów
Tablica content akceptuje dwa typy obiektów:
text: blok tekstowy z właściwościątextimage_url: odniesienie do obrazu z właściwościąimage_url
Możesz łączyć dowolną liczbę obiektów w jednej wiadomości. Na przykład, aby poprosić model o porównanie dwóch obrazów:
{
"role": "user",
"content": [
{"type": "text", "text": "Porównaj te dwa schematy architektury."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
Parametr detail dla obrazów
Każdy obiekt image_url akceptuje opcjonalny parametr detail, który kontroluje rozdzielczość analizy:
auto: model automatycznie wybiera poziom szczegółowości (wartość domyślna)low: szybka i ekonomiczna analiza, wystarczająca dla prostych obrazów (ikony, podstawowe diagramy)high: szczegółowa analiza, zalecana dla złożonych obrazów (dokumenty, fotografie, interfejsy)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Wybór poziomu szczegółowości bezpośrednio wpływa na liczbę zużytych tokenów, a tym samym na koszt żądania.
Kiedy użyć którego formatu?
Zasada jest prosta:
- Tylko tekst → format ciągu znaków (prostszy, bardziej czytelny)
- Tekst + obrazy → format tablicy (wymagany dla treści multimodalnych)
- Tylko obrazy → format tablicy zawierający wyłącznie obiekty
image_url
Format tablicy z pojedynczym obiektem text jest funkcjonalnie równoważny formatowi ciągu znaków, ale niepotrzebnie rozwlekły:
// Równoważne, ale niepotrzebnie skomplikowane
{"content": [{"type": "text", "text": "Cześć"}]}
// Preferuj tę formę
{"content": "Cześć"}
Ograniczenia techniczne dla obrazów
Zanim wyślesz obrazy do API xAI, pamiętaj o tych limitach:
- Maksymalny rozmiar: 20 MiB na obraz
- Akceptowane formaty: tylko JPG, JPEG, PNG (brak obsługi GIF, WebP ani SVG)
- Liczba: brak limitu liczby obrazów na żądanie
- Kompatybilne modele: tylko grok-4.5 i nowsze
Obrazy można dostarczyć za pomocą publicznego adresu URL lub zakodować w formacie base64 bezpośrednio w URL (format data:image/jpeg;base64,...).
Kluczowe wnioski
- Pole
contentakceptuje prosty ciąg znaków (tekst) lub tablicę obiektów (multimodalne) - Format tablicy wykorzystuje obiekty z polem
type:"text"lub"image_url" - Parametr
detail(auto,low,high) kontroluje rozdzielczość analizy obrazów - Obrazy są ograniczone do 20 MiB w formacie JPG/PNG i wymagają modelu grok-4.5 lub nowszego
- Używaj formatu ciągu znaków, gdy wysyłasz tylko tekst – jest bardziej czytelny i prostszy