input_image vs image_url: Iż-Żewġ Sintassi
F'din il-paġna
Żewġ API, żewġ sintassi
xAI toffri żewġ endpoints biex tinteraġixxi ma’ Grok, u kull wieħed juża sintassi differenti biex tibgħat l-immaġini. Li tifhem dawn id-differenzi huwa essenzjali biex tikteb kodiċi korrett u tevita żbalji frustranti.
API tar-Risposti: input_image (rakkomandat)
L-API tar-Risposti (Responses API) hija l-endpoint primarju l-ġdid ta’ xAI. Il-karatteristiċi l-ġodda jiżdiedu hawn l-ewwel. Din hija l-API li għandek tipprijoritizza għal kwalunkwe proġett ġdid.
Sintassi
{
"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."
}
]
}
Karatteristiċi
- It-tip huwa
input_image(mhuximage_url) - L-URL jew id-Data URI jmur direttament f’
image_url(l-ebda oġġett imbejjen) detailjinsab fl-istess livell bħalimage_url- It-test juża t-tip
input_text - L-array
inputjissostitwixxi l-arraymessagesmill-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 tal-Chat Completions: image_url (antikwat)
L-API tal-Chat Completions hija l-endpoint antikwat, miżmum għall-kompatibbiltà mal-SDKs eżistenti ta’ OpenAI. Jekk qed timmigra kodiċi miktub għal OpenAI, din l-API tiffaċilita t-tranżizzjoni.
Sintassi
{
"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."
}
]
}
]
}
Karatteristiċi
- It-tip huwa
image_url(mhuxinput_image) - L-URL jinsab f’oġġett imbejjen
image_url.url(doppju tbejjin) detailjinsab ġewwa l-oġġettimage_url- It-test juża t-tip
text(mhuxinput_text) - Il-messaġġi għandhom
role(system, user, assistant)
Python bl-SDK ta’ OpenAI
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)
Tabella ta’ tqabbil
| Aspett | API Responses | Chat Completions |
|---|---|---|
| Status | Primarju (rakkomandat) | Antikwat (għall-kompatibbiltà) |
| Tip ta' immaġni | input_image | image_url |
| Tip ta' test | input_text | text |
| URL tal-immaġni | image_url: "..." | image_url.url: "..." |
| Ġestjoni tal-istat | Stateful (previous_response_id) | Stateless (ibgħat kollox mill-ġdid) |
| Ħażna | store: true/false | Le (stateless) |
| Għodod tas-server | web_search, x_search, code_interpreter | Limitati |
Żbalji komuni tas-sintassi
Żball 1: Taħlit tal-formati
# SBALJAT — Sintassi ta' Chat Completions fl-API Responses
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Le!
]
# KORRETT — Sintassi tal-API Responses
input=[
{"type": "input_image", "image_url": "..."} # Iva!
]
Żball 2: Nsibu n-nuqqas ta’ struttura mbejjna f’Chat Completions
# SBALJAT — URL dirett f'Chat Completions
{"type": "image_url", "image_url": "https://..."} # Le!
# KORRETT — Oġġett imbejjen
{"type": "image_url", "image_url": {"url": "https://..."}} # Iva!
Żball 3: Użu ta’ “text” minflok “input_text”
# SBALJAT — Tip "text" fl-API Responses
input=[
{"type": "text", "text": "Describe."} # Le!
]
# KORRETT
input=[
{"type": "input_text", "text": "Describe."} # Iva!
]
Meta tuża liema API
- Proġett ġdid: uża l-API Responses. Tagħtik aċċess għall-aħħar karatteristiċi u l-ħażna tal-konversazzjoni.
- Migrazzjoni minn OpenAI: ibda b’Chat Completions biex timminimizza l-bidliet fil-kodiċi, imbagħad immigra gradwalment lejn l-API Responses.
- Immaġini sensittivi: API Responses b’
store: falsejew API Chat Completions (stateless b’mod naturali).
Punti Ewlenin
- L-API Responses tuża
input_image+input_text, l-API Chat Completions tużaimage_url+text - L-istruttura tal-URL tvarja: diretta fir-Responses, imbejjna f’Chat Completions
- L-API Responses hija l-għażla rakkomandata għal kull żvilupp ġdid
- Qatt ma tħallat is-sintassi miż-żewġ API fl-istess talba
- Dejjem iċċekkja t-tip tal-oġġett (
input_imagevsimage_url) biex tevita żbalji silenzjużi
Ittestja l-għarfien tiegħek
Viżjoni tal-API ta’ xAI: formati, tokens, sintassi—kollox fil-post?
1. Kif tibgħat immaġni lill-API?
Tweġiba: Permezz ta’ URL jew Base64, f’messaġġ b’kontenut imħallat—bir-rispett tal-format iddokumentat u r-restrizzjonijiet tad-daqs.
2. X'jikkontrolla l-parametru detail (auto, low, high)?
Tweġiba: Il-granularità tal-analiżi u l-ispiża: low tiffranka tokens għal każijiet ta’ użu grossolani, high timmassimizza l-preċiżjoni (OCR, dettalji fini), auto iħalli lill-API tiddeċiedi.
3. Kif tiġi kkalkulata l-ispiża ta' immaġni?
Tweġiba: F’tokens tal-immaġni—minn 256 sa 1792 skont ir-riżoluzzjoni u d-dettall: id-daqs tal-immaġni tiegħek u l-livell tad-dettall huma l-ewwel leva ta’ ottimizzazzjoni.
4. X'tippermetti t-tqabbil ta' immaġni multipli?
Tweġiba: Li tibgħat immaġni multipli f’talba waħda u tirraġuna fuqhom—differenzi, evoluzzjonijiet, konsistenza—bla limitu fuq in-numru ta’ immaġni għal kull talba.
5. input_image jew image_url: liema tagħżel?
Tweġiba: input_image hija s-sintassi moderna tal-API Responses; image_url tibqa’ bħala l-wirt ta’ Chat Completions—għal kodiċi ġdid, is-sintassi moderna hija obbligatorja.
Format tajjeb, dettall tajjeb, sintassi tajba: il-viżjoni tiġi ppiljata bħat-test—sa l-aħħar token.