input_image vs image_url: kaks süntaksit
Sellel lehel
Kaks API-d, kaks süntaksit
xAI pakub Grokiga suhtlemiseks kahte lõpppunkti ja kumbki kasutab piltide saatmiseks erinevat süntaksit. Nende erinevuste mõistmine on hädavajalik korrektse koodi kirjutamiseks ja tüütute vigade vältimiseks.
Responses API: input_image (soovitatav)
Responses API on xAI uus peamine lõpppunkt. Uued funktsioonid lisatakse esmalt siia. See on API, mida tuleks eelistada kõigis uutes projektides.
Süntaks
{
"model": "grok-4.5",
"store": false,
"input": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Kirjelda seda pilti."
}
]
}
Omadused
- Tüüp on
input_image(mitteimage_url) - URL või Data URI läheb otte
image_urlväljale (pesastatud objekti pole) detailasub samal tasemel kuiimage_url- Tekst kasutab tüüpi
input_text - Massiiv
inputasendab Chat Completionsi massiivimessages
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": "Kirjelda seda pilti."
}
],
store=False
)
print(response.output_text)
Chat Completions API: image_url (pärandvara)
Chat Completions API on pärandvara lõpppunkt, mida hallatakse ühilduvuse tagamiseks olemasolevate OpenAI SDK-dega. Kui migreerid OpenAI jaoks kirjutatud koodi, hõlbustab see API üleminekut.
Süntaks
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Kirjelda seda pilti."
}
]
}
]
}
Omadused
- Tüüp on
image_url(mitteinput_image) - URL asub pesastatud objektis
image_url.url(topeltpesastus) detailasub objektiimage_urlsees- Tekst kasutab tüüpi
text(mitteinput_text) - Sõnumitel on roll (
system,user,assistant)
Python koos OpenAI SDK-ga
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": "Kirjelda seda pilti."
}
]
}]
)
print(response.choices[0].message.content)
Võrdlustabel
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Olek | Peamine (soovitatav) | Pärandvara (ühilduvus) |
| Pildi tüüp | input_image | image_url |
| Teksti tüüp | input_text | text |
| Pildi URL | image_url: "..." | image_url.url: "..." |
| Oleku haldus | Olekuga (previous_response_id) | Olekuta (saada kõik uuesti) |
| Salvestamine | store: true/false | Ei (olekuta) |
| Serveri tööriistad | web_search, x_search, code_interpreter | Piiratud |
Levinud süntaksivead
Viga 1: Vormingute segamine
# VALE — Chat Completionsi süntaks Responses API-s
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ei!
]
# ÕIGE — Responses API süntaks
input=[
{"type": "input_image", "image_url": "..."} # Jah!
]
Viga 2: Pesastatud struktuuri unustamine Chat Completionsis
# VALE — Otse URL Chat Completionsis
{"type": "image_url", "image_url": "https://..."} # Ei!
# ÕIGE — Pesastatud objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Jah!
Viga 3: “text” kasutamine “input_text” asemel
# VALE — tüüp "text" Responses API-s
input=[
{"type": "text", "text": "Kirjelda."} # Ei!
]
# ÕIGE
input=[
{"type": "input_text", "text": "Kirjelda."} # Jah!
]
Millal kumb API valida
- Uus projekt: kasuta Responses API-d. See annab juurdepääsu uusimatele funktsioonidele ja vestluse salvestamisele.
- Migreerumine OpenAI-st: alusta Chat Completionsist, et minimeerida koodimuudatusi, seejärel migreeru järk-järgult Responses API-le.
- Tundlikud pildid: Responses API koos parameetriga
store: falsevõi Chat Completions API (oma olemuselt olekuta).
Peamised punktid
- Responses API kasutab
input_image+input_text, Chat Completions API kasutabimage_url+text - URL-i struktuur erineb: Responsesis otsene, Chat Completionsis pesastatud
- Responses API on soovitatav valik kogu uue arenduse jaoks
- Ära kunagi sega mõlema API süntakseid samas päringus
- Kontrolli alati objekti tüüpi (
input_imagevsimage_url), et vältida vaikivaid vigu
Testi oma teadmisi
xAI API nägemus: vormingud, tokenid, süntaksid – kas kõik on paigas?
1. Kuidas saadad pildi API-le?
Vastus: URL-i või Base64 kaudu, segasisulises sõnumis – järgides dokumenteeritud vormingu ja suuruse piiranguid.
2. Mida juhib parameeter detail (auto, low, high)?
Vastus: Analüüsi granulaarsust ja kulu: low säästab tokeneid üldiste kasutusjuhtude jaoks, high maksimeerib täpsust (OCR, peened detailid), auto jätab otsuse API-le.
3. Kuidas arvutatakse pildi hind?
Vastus: Pilditokenites – vahemikus 256 kuni 1792 sõltuvalt eraldusvõimest ja detailist: piltide suuruse ja detailitaseme kohandamine on esimene optimeerimise hoob.
4. Mida võimaldab mitme pildi võrdlus?
Vastus: Mitme pildi saatmist ühes päringus ja nende üle arutlemist – erinevused, arengud, järjepidevus – ilma piiranguta piltide arvule päringu kohta.
5. input_image või image_url: kumb valida?
Vastus: input_image on Responses API kaasaegne süntaks; image_url püsib Chat Completionsi pärandvarana – uue koodi jaoks on kaasaegne süntaks kohustuslik.
Hea vorming, hea detail, hea süntaks: nägemust juhitakse nagu teksti – tokeni täpsusega.