Przejdź do głównej treści
Polski— Wybierz język
Menu

Format treści: prosty ciąg znaków i tablica obiektów

Lekcja 3 z 12 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Dwa formaty pola content
  2. Format ciągu znaków: najczęstszy przypadek
  3. Format tablicy: treść multimodalna
  4. Kiedy użyć którego formatu?
  5. Ograniczenia techniczne dla obrazów
  6. Kluczowe wnioski

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ą text
  • image_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 content akceptuje 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