input_image naspram image_url: dvije sintakse
Na ovoj stranici
Dva API-ja, dvije sintakse
xAI nudi dvije krajnje točke (endpoints) za interakciju s Grokom, a svaka koristi različitu sintaksu za slanje slika. Razumijevanje ovih razlika ključno je za pisanje ispravnog koda i izbjegavanje frustrirajućih pogrešaka.
Responses API: input_image (preporučeno)
Responses API je nova glavna krajnja točka tvrtke xAI. Nove funkcije prvo se dodaju ovdje. Ovo je API koji trebaš prioritizirati za svaki novi projekt.
Sintaksa
{
"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."
}
]
}
Karakteristike
- Tip je
input_image(neimage_url) - URL ili Data URI ide izravno u
image_url(bez ugniježđenog objekta) detailse nalazi na istoj razini kaoimage_url- Tekst koristi tip
input_text - Niz
inputzamjenjuje nizmessagesiz Chat Completionsa
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 (zastarjelo)
Chat Completions API je zastarjela krajnja točka, održavana radi kompatibilnosti s postojećim OpenAI SDK-ovima. Ako migriraš kod napisan za OpenAI, ovaj API olakšava prijelaz.
Sintaksa
{
"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."
}
]
}
]
}
Karakteristike
- Tip je
image_url(neinput_image) - URL se nalazi u ugniježđenom objektu
image_url.url(dvostruko ugnježđivanje) detailse nalazi unutar objektaimage_url- Tekst koristi tip
text(neinput_text) - Poruke imaju
role(system, user, assistant)
Python s OpenAI SDK-om
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)
Tablica usporedbe
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Status | Glavni (preporučeno) | Zastarjeli (kompatibilnost) |
| Tip slike | input_image | image_url |
| Tip teksta | input_text | text |
| URL slike | image_url: "..." | image_url.url: "..." |
| Upravljanje stanjem | Stanje sačuvano (previous_response_id) | Bez stanja (ponovno slanje svega) |
| Pohrana | store: true/false | Ne (bez stanja) |
| Alati na poslužitelju | web_search, x_search, code_interpreter | Ograničeno |
Uobičajene sintaksne pogreške
Pogreška 1: Miješanje formata
# KRIVO — Sintaksa Chat Completionsa u Responses API-ju
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ne!
]
# ISPRAVNO — Sintaksa Responses API-ja
input=[
{"type": "input_image", "image_url": "..."} # Da!
]
Pogreška 2: Zaboravljanje ugniježđene strukture u Chat Completionsu
# KRIVO — Izravan URL u Chat Completionsu
{"type": "image_url", "image_url": "https://..."} # Ne!
# ISPRAVNO — Ugniježđeni objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Da!
Pogreška 3: Korištenje “text” umjesto “input_text”
# KRIVO — Tip "text" u Responses API-ju
input=[
{"type": "text", "text": "Describe."} # Ne!
]
# ISPRAVNO
input=[
{"type": "input_text", "text": "Describe."} # Da!
]
Kada koristiti koji API
- Novi projekt: koristi Responses API. On daje pristup najnovijim funkcijama i pohrani razgovora.
- Migracija s OpenAI-ja: započni s Chat Completionsom kako bi minimizirao promjene koda, zatim postupno migriraj na Responses API.
- Osjetljive slike: Responses API s
store: falseili Chat Completions API (po prirodi bez stanja).
Ključne točke
- Responses API koristi
input_image+input_text, dok Chat Completions API koristiimage_url+text - Struktura URL-a se razlikuje: izravna u Responsesu, ugniježđena u Chat Completionsu
- Responses API je preporučeni izbor za sav novi razvoj
- Nikada ne miješaj sintakse oba API-ja u istom zahtjevu
- Uvijek provjeri tip objekta (
input_imagenaspramimage_url) kako bi izbjegao tihe pogreške
Provjeri svoje znanje
xAI API vizija: formati, tokeni, sintakse — je li sve na mjestu?
1. Kako šalješ sliku API-ju?
Odgovor: Putem URL-a ili Base64 formata, u poruci mješovitog sadržaja — poštujući dokumentirana ograničenja formata i veličine.
2. Što kontrolira parametar detail (auto, low, high)?
Odgovor: Granularnost analize i trošak: low štedi tokene za grublje slučajeve uporabe, high maksimizira preciznost (OCR, fini detalji), auto prepušta odluku API-ju.
3. Kako se izračunava trošak slike?
Odgovor: U tokenima slike — od 256 do 1792, ovisno o razlučivosti i detalju: prilagodba veličine slika i razine detalja prvi je poluga optimizacije.
4. Što omogućuje usporedba više slika?
Odgovor: Slanje više slika u jednom zahtjevu i rezoniranje nad njima — razlike, evolucije, dosljednost — bez ograničenja broja slika po zahtjevu.
5. input_image ili image_url: što odabrati?
Odgovor: input_image je moderna sintaksa Responses API-ja; image_url ostaje kao naslijeđe Chat Completionsa — za novi kod, moderna sintaksa je obavezna.
Dobar format, dobar detalj, dobra sintaksa: vizija se upravlja poput teksta — sve do tokena.