input_image vs image_url: A két szintaxis
Ezen az oldalon
Két API, két szintaxis
Az xAI két végpontot kínál a Grokkal való kommunikációhoz, és mindegyik eltérő szintaxist használ a képek küldésére. E különbségek megértése elengedhetetlen a helyes kód írásához és a bosszantó hibák elkerüléséhez.
Responses API: input_image (ajánlott)
A Responses API az xAI új elsődleges végpontja. Az új funkciók itt jelennek meg először. Minden új projektnél ezt az API-t kell előnyben részesítened.
Szintaxis
{
"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."
}
]
}
Jellemzők
- A típus
input_image(nemimage_url) - Az URL vagy Data URI közvetlenül az
image_urlmezőbe kerül (nincs beágyazott objektum) - A
detailugyanazon a szinten helyezkedik el, mint azimage_url - A szöveg az
input_texttípust használja - Az
inputtömb helyettesíti a Chat Completionsmessagestömbjét
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)
Chat Completions API: image_url (örökölt)
A Chat Completions API az örökölt végpont, amelyet a meglévő OpenAI SDK-kkal való kompatibilitás érdekében tartanak fenn. Ha OpenAI-hoz írt kódot migrálsz, ez az API megkönnyíti az átállást.
Szintaxis
{
"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."
}
]
}
]
}
Jellemzők
- A típus
image_url(neminput_image) - Az URL egy beágyazott
image_url.urlobjektumban található (kettős beágyazás) - A
detailazimage_urlobjektumon belül helyezkedik el - A szöveg a
texttípust használja (nem azinput_text-et) - Az üzenetek rendelkeznek
roletulajdonsággal (system, user, assistant)
Python OpenAI SDK-val
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)
Összehasonlító táblázat
| Szempont | Responses API | Chat Completions |
|---|---|---|
| Státusz | Elsődleges (ajánlott) | Örökölt (kompatibilitás) |
| Kép típusa | input_image | image_url |
| Szöveg típusa | input_text | text |
| Kép URL | image_url: "..." | image_url.url: "..." |
| Állapotkezelés | Állapotfüggő (previous_response_id) | Állapotfüggetlen (mindent újra kell küldeni) |
| Tárolás | store: true/false | Nincs (állapotfüggetlen) |
| Szerveroldali eszközök | web_search, x_search, code_interpreter | Korlátozott |
Gyakori szintaktikai hibák
1. hiba: Formátumok keverése
# HELYTELEN — Chat Completions szintaxis a Responses API-ban
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nem!
]
# HELYES — Responses API szintaxis
input=[
{"type": "input_image", "image_url": "..."} # Igen!
]
2. hiba: A beágyazott szerkezet elfelejtése a Chat Completionsben
# HELYTELEN — Közvetlen URL a Chat Completionsben
{"type": "image_url", "image_url": "https://..."} # Nem!
# HELYES — Beágyazott objektum
{"type": "image_url", "image_url": {"url": "https://..."}} # Igen!
3. hiba: A „text“ használata az „input_text“ helyett
# HELYTELEN — „text“ típus a Responses API-ban
input=[
{"type": "text", "text": "Describe."} # Nem!
]
# HELYES
input=[
{"type": "input_text", "text": "Describe."} # Igen!
]
Mikor melyik API-t használd?
- Új projekt: használd a Responses API-t. Ez biztosít hozzáférést a legújabb funkciókhoz és a beszélgetések tárolásához.
- Migrálás OpenAI-ból: kezdd a Chat Completions API-val a kódmódosítások minimalizálása érdekében, majd fokozatosan térj át a Responses API-ra.
- Érzékeny képek: Responses API
store: falseparaméterrel, vagy Chat Completions API (természeténél fogva állapotfüggetlen).
Főbb megállapítások
- A Responses API az
input_image+input_textpárost használja, míg a Chat Completions API azimage_url+textkombinációt. - Az URL szerkezete eltérő: közvetlen a Responses API-ban, beágyazott a Chat Completionsben.
- A Responses API az ajánlott választás minden új fejlesztéshez.
- Soha ne keverd a két API szintaxisát ugyanabban a kérésben.
- Mindig ellenőrizd az objektum típusát (
input_imagevsimage_url) a csendes hibák elkerülése érdekében.
Teszteld a tudásod!
xAI API vision: formátumok, tokenek, szintaxisok – minden a helyén van?
1. Hogyan küldesz képet az API-nak?
Válasz: URL-en vagy Base64-en keresztül, vegyes tartalmú üzenetben – a dokumentált formátumi és méretkorlátok betartásával.
2. Mit szabályoz a detail paraméter (auto, low, high)?
Válasz: Az elemzés granularityását és költségét: a low tokeneket spórol durvább esetekben, a high maximalizálja a pontosságot (OCR, finom részletek), az auto pedig az API-ra bízza a döntést.
3. Hogyan számítják ki egy kép költségét?
Válasz: Képtokenekben – 256 és 1792 között, a felbontástól és a detail szinttől függően: a képek méretezése és a detail szint beállítása az első optimalizálási lehetőség.
4. Mire teszi lehetővé a több kép összehasonlítása?
Válasz: Több kép elküldésére egyetlen kérésben, és azok közötti következtetésre – különbségek, fejlődés, konzisztencia –, a kérésenkénti képek számának korlátozása nélkül.
5. input_image vagy image_url: melyiket válaszd?
Válasz: Az input_image a Responses API modern szintaxisa; az image_url a Chat Completions örökségeként marad fenn – új kód esetén a modern szintaxis kötelező.
Jó formátum, jó detail, jó szintaxis: a vision-t ugyanúgy irányítjuk, mint a szöveget – egészen a tokenek szintjéig.