input_image vs image_url: Dve syntaxe
Na tejto strane
Dve API, dve syntaxe
xAI ponúka dva koncové body pre interakciu s Grokom a každý z nich používa odlišnú syntax na odosielanie obrázkov. Pochopenie týchto rozdielov je kľúčové pre písanie správneho kódu a vyhnutie sa frustrujúcim chybám.
Responses API: input_image (odporúčané)
Responses API je nový hlavný koncový bod xAI. Nové funkcie sa pridávajú najprv sem. Toto je API, ktoré by si mal uprednostniť pri akomkoľvek novom projekte.
Syntax
{
"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."
}
]
}
Charakteristika
- Typ je
input_image(nieimage_url) - URL alebo Data URI ide priamo do
image_url(žiadny vnorený objekt) detailsa nachádza na rovnakej úrovni akoimage_url- Text používa typ
input_text - Pole
inputnahrádza polemessagesz 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)
Chat Completions API: image_url (staršie)
Chat Completions API je starší koncový bod, udržiavaný pre kompatibilitu s existujúcimi SDK OpenAI. Ak migruješ kód napísaný pre OpenAI, toto API uľahčí prechod.
Syntax
{
"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."
}
]
}
]
}
Charakteristika
- Typ je
image_url(nieinput_image) - URL sa nachádza vo vnorenom objekte
image_url.url(dvojité vnorenie) detailsa nachádza vo vnútri objektuimage_url- Text používa typ
text(nieinput_text) - Správy majú rolu (
system,user,assistant)
Python s 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)
Porovnávacia tabuľka
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Stav | Hlavné (odporúčané) | Staršie (kompatibilita) |
| Typ obrázka | input_image | image_url |
| Typ textu | input_text | text |
| URL obrázka | image_url: "..." | image_url.url: "..." |
| Správa stavu | Stavové (previous_response_id) | Bezstavové (odoslať všetko znova) |
| Ukladanie | store: true/false | Nie (bezstavové) |
| Nástroje na strane servera | web_search, x_search, code_interpreter | Obmedzené |
Časté chyby v syntaxi
Chyba 1: Miešanie formátov
# ZLE — Syntax Chat Completions v Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nie!
]
# SPRÁVNE — Syntax Responses API
input=[
{"type": "input_image", "image_url": "..."} # Áno!
]
Chyba 2: Zabudnutie na vnorenú štruktúru v Chat Completions
# ZLE — Priame URL v Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nie!
# SPRÁVNE — Vnorený objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Áno!
Chyba 3: Použitie “text” namiesto “input_text”
# ZLE — Typ "text" v Responses API
input=[
{"type": "text", "text": "Describe."} # Nie!
]
# SPRÁVNE
input=[
{"type": "input_text", "text": "Describe."} # Áno!
]
Kedy použiť ktoré API
- Nový projekt: použi Responses API. Poskytuje prístup k najnovším funkciám a ukladaniu konverzácií.
- Migrácia z OpenAI: začni s Chat Completions, aby si minimalizoval zmeny v kóde, a následne postupne migruj na Responses API.
- Citlivé obrázky: Responses API s
store: falsealebo Chat Completions API (prirodzene bezstavové).
Kľúčové poznatky
- Responses API používa
input_image+input_text, Chat Completions API používaimage_url+text - Štruktúra URL sa líši: priama v Responses, vnorená v Chat Completions
- Responses API je odporúčanou voľbou pre všetok nový vývoj
- Nikdy nemiešaj syntaxe z oboch API v jednej požiadavke
- Vždy skontroluj typ objektu (
input_imagevsimage_url), aby si sa vyhol tichým chybám
Otestuj si svoje vedomosti
Vízia API xAI: formáty, tokeny, syntaxe – je všetko na mieste?
1. Ako odošleš obrázok do API?
Odpoveď: Prostredníctvom URL alebo Base64, v správe so zmiešaným obsahom – pri dodržaní zdokumentovaných obmedzení formátu a veľkosti.
2. Čo riadi parameter detail (auto, low, high)?
Odpoveď: Granularitu analýzy a náklady: low šetrí tokeny pre hrubšie prípady použitia, high maximalizuje presnosť (OCR, jemné detaily), auto nechá rozhodnúť API.
3. Ako sa vypočítavajú náklady na obrázok?
Odpoveď: V obrazových tokenoch – od 256 do 1792 v závislosti od rozlíšenia a detailu: zmenšovanie veľkosti obrázkov a úroveň detailu je prvým pákou optimalizácie.
4. Čo umožňuje porovnávanie viacerých obrázkov?
Odpoveď: Odoslanie viacerých obrázkov v jednej požiadavke a uvažovanie nad nimi – rozdiely, vývoj, konzistencia – bez obmedzenia počtu obrázkov na požiadavku.
5. input_image alebo image_url: čo si vybrať?
Odpoveď: input_image je moderná syntax Responses API; image_url pretrváva ako staršie riešenie Chat Completions – pre nový kód je moderná syntax povinná.
Správny formát, správny detail, správna syntax: vízia sa riadi ako text – až po token.