Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

input_image vs image_url: A két szintaxis

12. lecke 12 közül Frissítve 2026. július 30. Kezdő
Ezen az oldalon
  1. Két API, két szintaxis
  2. Responses API: input_image (ajánlott)
  3. Chat Completions API: image_url (örökölt)
  4. Összehasonlító táblázat
  5. Gyakori szintaktikai hibák
  6. Mikor melyik API-t használd?
  7. Főbb megállapítások
  8. Teszteld a tudásod!

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 (nem image_url)
  • Az URL vagy Data URI közvetlenül az image_url mezőbe kerül (nincs beágyazott objektum)
  • A detail ugyanazon a szinten helyezkedik el, mint az image_url
  • A szöveg az input_text típust használja
  • Az input tömb helyettesíti a Chat Completions messages tö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 (nem input_image)
  • Az URL egy beágyazott image_url.url objektumban található (kettős beágyazás)
  • A detail az image_url objektumon belül helyezkedik el
  • A szöveg a text típust használja (nem az input_text-et)
  • Az üzenetek rendelkeznek role tulajdonsá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: false paramé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_text párost használja, míg a Chat Completions API az image_url + text kombiná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_image vs image_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.