input_image vs image_url: Dwie składnie
Na tej stronie
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 nieimage_url) - Adres URL lub Data URI znajduje się bezpośrednio w polu
image_url(bez zagnieżdżonego obiektu) - Pole
detailznajduje się na tym samym poziomie coimage_url - Tekst używa typu
input_text - Tablica
inputzastępuje tablicęmessagesz 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 nieinput_image) - Adres URL znajduje się w zagnieżdżonym obiekcie
image_url.url(podwójne zagnieżdżenie) - Pole
detailznajduje się wewnątrz obiektuimage_url - Tekst używa typu
text(a nieinput_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: falselub API Chat Completions (z natury bezstanowe).
Kluczowe wnioski
- API Responses używa
input_image+input_text, podczas gdy API Chat Completions używaimage_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_imagevsimage_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.