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

Formaty obrazów: URL i Base64

Lekcja 1 z 12 Zaktualizowano 3 listopada 2026 Początkujący
Na tej stronie
  1. Wysyłanie obrazów do Grok
  2. Bezpośredni adres URL
  3. Kodowanie Base64 (Data URI)
  4. Kluczowe różnice między URL a Base64
  5. Łączenie tekstu i obrazów
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. W przypadku interfejsu API Responses obiekty input_image i input_text umieszcza się w polu content wiadomości {"role": "user", ...}, a nie bezpośrednio w input. Przykład w języku Python wcześniej wywoływał client.responses.create() na kliencie xai-sdk, który nie posiada tej metody, i zawierał klucz API w kodzie: teraz używa funkcji user(...) i image(...) z SDK, a klucz jest odczytywany ze zmiennych środowiskowych. Dodano ostrzeżenie xAI dotyczące przechowywania historii. Kod zweryfikowany z xai-sdk 1.21.0. Źródło: Image Understanding.

Wysyłanie obrazów do Grok

Grok analizujący obraz 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.

2
Obsługiwane formaty
20 MiB
Maksymalny rozmiar na obraz
JPG/PNG
Akceptowane formaty
Bez ograniczeń
Liczba obrazów

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/JPEG
  • data: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_image w polu content wiadomości; Chat Completions używa części image_url; SDK xAI używa image() wewnątrz user()
  • Preferuj URL dla obrazów publicznych, a Base64 dla plików lokalnych