input_image vs image_url: dvi sintaksės
Šiame puslapyje
Dvi API, dvi sintaksės
xAI siūlo du galinius taškus (endpoints) darbui su „Grok“, ir kiekvienas naudoja skirtingą vaizdų siuntimo sintaksę. Suprasti šiuos skirtumus yra būtina norint rašyti teisingą kodą ir išvengti varginančių klaidų.
Responses API: input_image (rekomenduojama)
Responses API yra naujas pagrindinis xAI galinis taškas. Naujos funkcijos pirmiausia diegiamos čia. Tai API, kurį turėtum pasirinkti bet kokiam naujam projektui.
Sintaksė
{
"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."
}
]
}
Charakteristikos
- Tipas yra
input_image(neimage_url) - URL arba duomenų URI (Data URI) įrašomas tiesiai į
image_url(be įdėto objekto) detailyra tame pačiame lygmenyje kaip irimage_url- Tekstui naudojamas
input_texttipas - Masyvas
inputpakeičia masyvąmessagesiš „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 (senoji versija)
„Chat Completions“ API yra senasis galinis taškas, palaikomas dėl suderinamumo su esamais „OpenAI“ SDK. Jei perkeli kodą, parašytą „OpenAI“, šis API palengvina perėjimą.
Sintaksė
{
"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."
}
]
}
]
}
Charakteristikos
- Tipas yra
image_url(neinput_image) - URL yra įdėtame
image_url.urlobjekte (dvigubas įdėjimas) detailyraimage_urlobjekto viduje- Tekstui naudojamas
texttipas (neinput_text) - Žinutės turi
role(system, user, assistant)
Python su 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)
Palyginimo lentelė
| Aspektas | API Responses | Chat Completions |
|---|---|---|
| Būsena | Pirminė (rekomenduojama) | Senoji (suderinamumui) |
| Vaizdo tipas | input_image | image_url |
| Teksto tipas | input_text | text |
| Vaizdo URL | image_url: "..." | image_url.url: "..." |
| Būsenos valdymas | Su būsena (previous_response_id) | Be būsenos (siųsti viską iš naujo) |
| Saugojimas | store: true/false | Ne (be būsenos) |
| Serverio įrankiai | web_search, x_search, code_interpreter | Riboti |
Dažnos sintaksės klaidos
1 klaida: Formatų maišymas
# NETEISINGA — Chat Completions sintaksė Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ne!
]
# TEISINGA — Responses API sintaksė
input=[
{"type": "input_image", "image_url": "..."} # Taip!
]
2 klaida: Pamiršta įdėta struktūra „Chat Completions“
# NETEISINGA — Tiesioginis URL „Chat Completions“
{"type": "image_url", "image_url": "https://..."} # Ne!
# TEISINGA — Įdėtas objektas
{"type": "image_url", "image_url": {"url": "https://..."}} # Taip!
3 klaida: Naudojamas „text“ vietoj „input_text“
# NETEISINGA — „text“ tipas Responses API
input=[
{"type": "text", "text": "Describe."} # Ne!
]
# TEISINGA
input=[
{"type": "input_text", "text": "Describe."} # Taip!
]
Kada naudoti kurį API
- Naujas projektas: naudok Responses API. Jis suteikia prieigą prie naujausių funkcijų ir pokalbių saugojimo.
- Perkėlimas iš „OpenAI“: pradėk nuo „Chat Completions“, kad sumažintum kodo pakeitimus, o tada palaipsniui pereik prie Responses API.
- Jautrūs vaizdai: Responses API su
store: falsearba „Chat Completions“ API (iš prigimties be būsenos).
Svarbiausi punktai
- Responses API naudoja
input_image+input_text, o „Chat Completions“ API naudojaimage_url+text. - URL struktūra skiriasi: tiesioginė „Responses“, įdėta – „Chat Completions“.
- Responses API yra rekomenduojamas pasirinkimas visai naujai kūrybai.
- Niekada nemaišyk abiejų API sintaksių tame pačiame užklausos prašyme.
- Visada tikrink objekto tipą (
input_imagepriešimage_url), kad išvengtum paslėptų klaidų.
Patikrink savo žinias
xAI API regėjimas: formatai, tokenai, sintaksės – ar viskas savo vietose?
1. Kaip siunčiamas vaizdas į API?
Atsakymas: Per URL arba Base64, mišraus turinio žinutėje – laikantis dokumentuotų formato ir dydžio apribojimų.
2. Ką kontroliuoja parametras detail (auto, low, high)?
Atsakymas: Analizės granuliariškumą ir kainą: low taupo tokenus bendriems atvejams, high maksimaliai padidina tikslumą (OCR, smulkios detalės), auto leidžia API nuspręsti.
3. Kaip apskaičiuojama vaizdo kaina?
Atsakymas: Vaizdo tokenais – nuo 256 iki 1792, priklausomai nuo skiriamosios gebos ir detalumo lygio: vaizdų dydžio ir detalumo lygio parinkimas yra pirmasis optimizavimo svertas.
4. Ką leidžia daryti kelių vaizdų palyginimas?
Atsakymas: Siųsti kelis vaizdus viename prašyme ir atlikti jų analizę – skirtumus, pokyčius, nuoseklumą – be jokio vaizdų skaičiaus ribojimo viename prašyme.
5. input_image ar image_url: ką pasirinkti?
Atsakymas: input_image yra šiuolaikinė Responses API sintaksė; image_url išlieka kaip „Chat Completions“ palikimas – naujam kodui privaloma naudoti šiuolaikinę sintaksę.
Geras formatas, geras detalumas, gera sintaksė: regėjimas valdomas kaip tekstas – iki pat tokeno.