input_image proti image_url: dva sintaksi
Na tej strani
Dva API-ja, dve sintaksi
xAI ponuja dve končni točki za interakcijo z Grokom, pri čemer vsaka uporablja drugačno sintakso za pošiljanje slik. Razumevanje teh razlik je ključno za pisanje pravilne kode in izogibanje frustrirajočim napakam.
API za odgovore (Responses API): input_image (priporočeno)
API za odgovore je nova glavna končna točka xAI. Nove funkcije so najprej dodane tukaj. To je API, ki ga moraš dati na prvo mesto pri vsakem novem projektu.
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."
}
]
}
Značilnosti
- Tip je
input_image(neimage_url) - URL ali Data URI gre neposredno v
image_url(brez gnezdenega objekta) detailje na isti ravni kotimage_url- Besedilo uporablja tip
input_text - Polje
inputnadomesti poljemessagesiz 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)
API Chat Completions: image_url (starejši)
API Chat Completions je starejša končna točka, ki se vzdržuje zaradi združljivosti z obstoječimi SDK-ji OpenAI. Če seliš kodo, napisano za OpenAI, ta API olajša prehod.
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."
}
]
}
]
}
Značilnosti
- Tip je
image_url(neinput_image) - URL se nahaja v gnezdenem objektu
image_url.url(dvojno gnezdenje) detailse nahaja znotraj objektaimage_url- Besedilo uporablja tip
text(neinput_text) - Sporočila imajo vlogo
role(system, user, assistant)
Python z 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)
Primerjalna tabela
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Status | Glavni (priporočeno) | Starejši (združljivost) |
| Tip slike | input_image | image_url |
| Tip besedila | input_text | text |
| URL slike | image_url: "..." | image_url.url: "..." |
| Upravljanje stanja | Stanjsko (previous_response_id) | Brez stanja (ponovno pošlji vse) |
| Shranjevanje | store: true/false | Ne (brez stanja) |
| Orodja na strežniku | web_search, x_search, code_interpreter | Omejeno |
Pogoste sintaktične napake
Napaka 1: Mešanje formatov
# NARARNO — Sintaksa Chat Completions v API-ju Responses
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ne!
]
# PRAVILNO — Sintaksa API-ja Responses
input=[
{"type": "input_image", "image_url": "..."} # Da!
]
Napaka 2: Pozabljanje gnezdena struktura v Chat Completions
# NARARNO — Neposreden URL v Chat Completions
{"type": "image_url", "image_url": "https://..."} # Ne!
# PRAVILNO — Gnezden objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Da!
Napaka 3: Uporaba “text” namesto “input_text”
# NARARNO — Tip "text" v API-ju Responses
input=[
{"type": "text", "text": "Describe."} # Ne!
]
# PRAVILNO
input=[
{"type": "input_text", "text": "Describe."} # Da!
]
Kdaj uporabiti kateri API
- Nov projekt: uporabi API za odgovore (Responses API). Omogoča dostop do najnovejših funkcij in shranjevanja pogovorov.
- Selitev z OpenAI: začni s Chat Completions, da zmanjšaš spremembe v kodi, nato pa postopoma preidi na API za odgovore.
- Občutljive slike: API za odgovore z
store: falseali API Chat Completions (po naravi brez stanja).
Ključne ugotovitve
- API za odgovore uporablja
input_image+input_text, API Chat Completions pa uporabljaimage_url+text. - Struktura URL-ja se razlikuje: neposredna v API-ju Responses, gnezdena v Chat Completions.
- API za odgovore je priporočena izbira za ves nov razvoj.
- Nikoli ne mešaj sintaks obeh API-jev v istem zahtevku.
- Vedno preveri tip objekta (
input_imageprotiimage_url), da se izogneš tihih napakam.
Preveri svoje znanje
Vizija API-ja xAI: formati, žetoni, sintakse – je vse na mestu?
1. Kako pošlješ sliko API-ju?
Odgovor: Prek URL-ja ali Base64, v sporočilu z mešano vsebino – ob upoštevanju dokumentiranih omejitev formata in velikosti.
2. Kaj nadzoruje parameter detail (auto, low, high)?
Odgovor: Granularnost analize in stroške: low prihrani žetone za grobe primere uporabe, high maksimira natančnost (OCR, fine podrobnosti), auto pa prepusti odločitev API-ju.
3. Kako se izračuna strošek slike?
Odgovor: V žetonih slike – od 256 do 1792, odvisno od ločljivosti in podrobnosti: prilagajanje velikosti slik in ravni podrobnosti je prvi vzvod za optimizacijo.
4. Kaj omogoča primerjava več slik?
Odgovor: Pošiljanje več slik v enem zahtevku in sklepanje o njih – razlike, evolucije, doslednost – brez omejitve števila slik na zahtevek.
5. input_image ali image_url: kaj izbrati?
Odgovor: input_image je sodobna sintaksa API-ja Responses; image_url ostaja kot dediščina Chat Completions – za novo kodo je sodobna sintaksa obvezna.
Dober format, dobra podrobnost, dobra sintaksa: vizija je vodena kot besedilo – vse do žetona.