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

input_image vs image_url: Dwie składnie

Lekcja 12 z 12 Zaktualizowano 30 lipca 2026 Początkujący
Na tej stronie
  1. Dwa interfejsy API, dwie składnie
  2. Interfejs API Responses: input_image (zalecane)
  3. Interfejs API Chat Completions: image_url (przestarzały)
  4. Tabela porównawcza
  5. Częste błędy składniowe
  6. Kiedy używać którego API
  7. Kluczowe wnioski
  8. Sprawdź swoją wiedzę

Dwa interfejsy API, dwie składnie

xAI udostępnia dwa punkty końcowe do interakcji z modelem Grok, z których każdy wykorzystuje inną składnię przesyłania obrazów. Zrozumienie tych różnic jest kluczowe dla pisania poprawnego kodu i unikania frustrujących błędów.

Interfejs API Responses: input_image (zalecane)

Interfejs API Responses to nowy główny punkt końcowy xAI. Nowe funkcje są tutaj wprowadzane jako pierwsze. To właśnie to API powinno być priorytetem dla każdego nowego projektu.

Składnia

{
  "model": "grok-4.5",
  "store": false,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://exemple.com/photo.jpg",
      "detail": "high"
    },
    {
      "type": "input_text",
      "text": "Describe this image."
    }
  ]
}

Charakterystyka

  • Typ to input_image (a nie image_url)
  • Adres URL lub Data URI znajduje się bezpośrednio w polu image_url (bez zagnieżdżonego obiektu)
  • Pole detail znajduje się na tym samym poziomie co image_url
  • Tekst używa typu input_text
  • Tablica input zastępuje tablicę messages z interfejsu Chat Completions

Python SDK

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_image",
            "image_url": "https://exemple.com/photo.jpg",
            "detail": "high"
        },
        {
            "type": "input_text",
            "text": "Describe this image."
        }
    ],
    store=False
)

print(response.output_text)

Interfejs API Chat Completions: image_url (przestarzały)

Interfejs API Chat Completions to punkt końcowy legacy, utrzymywany dla zapewnienia kompatybilności z istniejącymi SDK OpenAI. Jeśli migrujesz kod napisany dla OpenAI, to API ułatwi przejście.

Składnia

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo.jpg",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Describe this image."
        }
      ]
    }
  ]
}

Charakterystyka

  • Typ to image_url (a nie input_image)
  • Adres URL znajduje się w zagnieżdżonym obiekcie image_url.url (podwójne zagnieżdżenie)
  • Pole detail znajduje się wewnątrz obiektu image_url
  • Tekst używa typu text (a nie input_text)
  • Wiadomości posiadają pole role (system, user, assistant)

Python z OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://exemple.com/photo.jpg",
                    "detail": "high"
                }
            },
            {
                "type": "text",
                "text": "Describe this image."
            }
        ]
    }]
)

print(response.choices[0].message.content)

Tabela porównawcza

Aspekt API Responses Chat Completions
Status Główny (zalecany) Legacy (kompatybilność)
Typ obrazu input_image image_url
Typ tekstu input_text text
URL obrazu image_url: "..." image_url.url: "..."
Zarządzanie stanem Stanowy (previous_response_id) Bezstanowy (wyślij wszystko ponownie)
Przechowywanie store: true/false Nie (bezstanowy)
Narzędzia serwerowe web_search, x_search, code_interpreter Ograniczone

Częste błędy składniowe

Błąd 1: Mieszanie formatów

# ŹLE — składnia Chat Completions w API Responses
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Nie!
]

# DOBRZE — składnia API Responses
input=[
    {"type": "input_image", "image_url": "..."}  # Tak!
]

Błąd 2: Zapomnienie o strukturze zagnieżdżonej w Chat Completions

# ŹLE — bezpośredni URL w Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Nie!

# DOBRZE — obiekt zagnieżdżony
{"type": "image_url", "image_url": {"url": "https://..."}}  # Tak!

Błąd 3: Użycie „text“ zamiast „input_text“

# ŹLE — typ "text" w API Responses
input=[
    {"type": "text", "text": "Describe."}  # Nie!
]

# DOBRZE
input=[
    {"type": "input_text", "text": "Describe."}  # Tak!
]

Kiedy używać którego API

  • Nowy projekt: użyj API Responses. Daje ono dostęp do najnowszych funkcji i przechowywania konwersacji.
  • Migracja z OpenAI: zacznij od Chat Completions, aby zminimalizować zmiany w kodzie, a następnie stopniowo migruj do API Responses.
  • Wrażliwe obrazy: API Responses z store: false lub API Chat Completions (z natury bezstanowe).

Kluczowe wnioski

  • API Responses używa input_image + input_text, podczas gdy API Chat Completions używa image_url + text.
  • Struktura URL różni się: bezpośrednia w Responses, zagnieżdżona w Chat Completions.
  • API Responses to zalecany wybór dla wszelkich nowych prac deweloperskich.
  • Nigdy nie mieszaj składni z obu interfejsów API w tym samym żądaniu.
  • Zawsze sprawdzaj typ obiektu (input_image vs image_url), aby uniknąć cichych błędów.

Sprawdź swoją wiedzę

Wizja API xAI: formaty, tokeny, składnie – czy wszystko jest na miejscu?

1. Jak wysłać obraz do API?

Odpowiedź: Poprzez URL lub Base64, w wiadomości o mieszanej zawartości – z zachowaniem udokumentowanych ograniczeń dotyczących formatu i rozmiaru.

2. Co kontroluje parametr detail (auto, low, high)?

Odpowiedź: Ziarnistość analizy i koszt: low oszczędza tokeny dla przypadków użycia o niskiej szczegółowości, high maksymalizuje precyzję (OCR, drobne detale), auto pozwala API podjąć decyzję.

3. Jak obliczany jest koszt obrazu?

Odpowiedź: W tokenach obrazu – od 256 do 1792 w zależności od rozdzielczości i poziomu detail: dostosowanie rozmiaru obrazów i poziomu detail to pierwszy dźwignia optymalizacji.

4. Co umożliwia porównywanie wielu obrazów?

Odpowiedź: Wysyłanie wielu obrazów w jednym żądaniu i wnioskowanie na ich temat – różnice, ewolucje, spójność – bez limitu liczby obrazów na żądanie.

5. input_image czy image_url: co wybrać?

Odpowiedź: input_image to nowoczesna składnia API Responses; image_url persists jako legacy Chat Completions – dla nowego kodu nowoczesna składnia jest obowiązkowa.

Dobry format, dobry detail, dobra składnia: wizja jest pilotowana jak tekst – aż do poziomu tokena.