input_image vs image_url: Dva typy syntaxe
Na této stránce
Dvě API, dvě syntaxe
xAI nabízí dva koncové body pro interakci s modelem Grok a každý z nich používá odlišnou syntaxi pro odesílání obrázků. Pochopení těchto rozdílů je zásadní pro psaní správného kódu a vyhnutí se frustrujícím chybám.
Responses API: input_image (doporučeno)
Responses API je nový hlavní koncový bod od xAI. Nové funkce jsou zde přidávány jako první. Toto je API, které bys měl upřednostnit pro jakýkoli nový projekt.
Syntaxe
{
"model": "grok-4.5",
"store": false,
"input": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Popiš tento obrázek."
}
]
}
Charakteristiky
- Typ je
input_image(nikoliimage_url) - URL nebo Data URI jde přímo do
image_url(žádný vnořený objekt) detailse nachází na stejné úrovni jakoimage_url- Text používá typ
input_text - Pole
inputnahrazuje 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": "Popiš tento obrázek."
}
],
store=False
)
print(response.output_text)
Chat Completions API: image_url (starší verze)
Chat Completions API je starší koncový bod, udržovaný pro kompatibilitu s existujícími SDK od OpenAI. Pokud migruješ kód napsaný pro OpenAI, toto API usnadní přechod.
Syntaxe
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Popiš tento obrázek."
}
]
}
]
}
Charakteristiky
- Typ je
image_url(nikoliinput_image) - URL se nachází ve vnořeném objektu
image_url.url(dvojí vnoření) detailse nachází uvnitř objektuimage_url- Text používá typ
text(nikoliinput_text) - Zprávy mají
role(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": "Popiš tento obrázek."
}
]
}]
)
print(response.choices[0].message.content)
Srovnávací tabulka
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Stav | Hlavní (doporučeno) | Starší (kompatibilita) |
| Typ obrázku | input_image | image_url |
| Typ textu | input_text | text |
| URL obrázku | image_url: "..." | image_url.url: "..." |
| Správa stavu | Stavová (previous_response_id) | Bezstavová (odeslat vše znovu) |
| Ukládání | store: true/false | Ne (bezstavové) |
| Nástroje na serveru | web_search, x_search, code_interpreter | Omezené |
Časté chyby v syntaxi
Chyba 1: Míchání formátů
# ŠPATNĚ — Syntaxe Chat Completions v Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ne!
]
# SPRÁVNĚ — Syntaxe Responses API
input=[
{"type": "input_image", "image_url": "..."} # Ano!
]
Chyba 2: Zapomenutí vnořené struktury v Chat Completions
# ŠPATNĚ — Přímá URL v Chat Completions
{"type": "image_url", "image_url": "https://..."} # Ne!
# SPRÁVNĚ — Vnořený objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Ano!
Chyba 3: Použití “text” místo “input_text”
# ŠPATNĚ — Typ "text" v Responses API
input=[
{"type": "text", "text": "Popiš."} # Ne!
]
# SPRÁVNĚ
input=[
{"type": "input_text", "text": "Popiš."} # Ano!
]
Kdy použít které API
- Nový projekt: použij Responses API. Poskytuje přístup k nejnovějším funkcím a ukládání konverzací.
- Migrace z OpenAI: začni s Chat Completions, abys minimalizoval změny v kódu, a poté postupně migruj na Responses API.
- Citlivé obrázky: Responses API s
store: falsenebo Chat Completions API (přirozeně bezstavové).
Klíčové poznatky
- Responses API používá
input_image+input_text, Chat Completions API používáimage_url+text - Struktura URL se liší: přímá v Responses, vnořená v Chat Completions
- Responses API je doporučená volba pro veškerý nový vývoj
- Nikdy nemíchej syntaxe z obou API v jedné žádosti
- Vždy zkontroluj typ objektu (
input_imagevsimage_url), abys předešel tichým chybám
Ověř si své znalosti
Vize API xAI: formáty, tokeny, syntaxe – je vše na místě?
1. Jak odešleš obrázek do API?
Odpověď: Prostřednictvím URL nebo Base64, ve zprávě se smíšeným obsahem – při dodržení zdokumentovaných formátových a velikostních omezení.
2. Co řídí parametr detail (auto, low, high)?
Odpověď: Granularitu analýzy a náklady: low šetří tokeny pro hrubé případy použití, high maximalizuje přesnost (OCR, jemné detaily), auto nechá rozhodnutí na API.
3. Jak se počítají náklady na obrázek?
Odpověď: V obrazových tokenech – od 256 do 1792 v závislosti na rozlišení a detailu: změna velikosti obrázků a úrovně detailu je prvním pákou optimalizace.
4. Co umožňuje porovnávání více obrázků?
Odpověď: Odeslání více obrázků v jedné žádosti a uvažování nad nimi – rozdíly, vývoj, konzistence – bez omezení počtu obrázků na žádost.
5. input_image nebo image_url: co vybrat?
Odpověď: input_image je moderní syntaxe Responses API; image_url přetrvává jako starší verze Chat Completions – pro nový kód je moderní syntaxe povinná.
Správný formát, správný detail, správná syntaxe: vize se řídí jako text – až na úroveň tokenu.