input_image vs image_url: Cele două sintaxe
Pe această pagină
Două API-uri, două sintaxe
xAI oferă două puncte de terminare (endpoints) pentru interacțiunea cu Grok, iar fiecare utilizează o sintaxă diferită pentru trimiterea imaginilor. Înțelegerea acestor diferențe este esențială pentru scrierea unui cod corect și evitarea erorilor frustrante.
API-ul Responses: input_image (recomandat)
API-ul Responses este noul punct de terminare principal al xAI. Noile funcționalități sunt adăugate aici în primul rând. Acesta este API-ul pe care trebuie să îl prioritizați pentru orice proiect nou.
Sintaxă
{
"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."
}
]
}
Caracteristici
- Tipul este
input_image(nuimage_url) - URL-ul sau Data URI merge direct în
image_url(fără obiect imbricat) detailse află la același nivel cuimage_url- Textul folosește tipul
input_text - Tabloul
inputînlocuiește tabloulmessagesdin Chat Completions
SDK Python
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-ul Chat Completions: image_url (vechi)
API-ul Chat Completions este punctul de terminare vechi (legacy), menținut pentru compatibilitatea cu SDK-urile OpenAI existente. Dacă migrați cod scris pentru OpenAI, acest API facilitează tranziția.
Sintaxă
{
"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."
}
]
}
]
}
Caracteristici
- Tipul este
image_url(nuinput_image) - URL-ul se află într-un obiect imbricat
image_url.url(dublă imbricare) detailse află în interiorul obiectuluiimage_url- Textul folosește tipul
text(nuinput_text) - Mesajele au un
role(system, user, assistant)
Python cu SDK 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)
Tabel comparativ
| Aspect | API Responses | Chat Completions |
|---|---|---|
| Stare | Principal (recomandat) | Vechi (compatibilitate) |
| Tip imagine | input_image | image_url |
| Tip text | input_text | text |
| URL imagine | image_url: "..." | image_url.url: "..." |
| Gestionarea stării | Cu stare (previous_response_id) | Fără stare (retrimitere totală) |
| Stocare | store: true/false | Nu (fără stare) |
| Instrumente server | web_search, x_search, code_interpreter | Limitate |
Erori frecvente de sintaxă
Eroarea 1: Amestecarea formatelor
# GREȘIT — Sintaxă Chat Completions în API-ul Responses
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nu!
]
# CORECT — Sintaxă API Responses
input=[
{"type": "input_image", "image_url": "..."} # Da!
]
Eroarea 2: Omiterea structurii imbricate în Chat Completions
# GREȘIT — URL direct în Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nu!
# CORECT — Obiect imbricat
{"type": "image_url", "image_url": {"url": "https://..."}} # Da!
Eroarea 3: Utilizarea „text“ în loc de „input_text“
# GREȘIT — Tipul "text" în API-ul Responses
input=[
{"type": "text", "text": "Describe."} # Nu!
]
# CORECT
input=[
{"type": "input_text", "text": "Describe."} # Da!
]
Când să utilizați fiecare API
- Proiect nou: utilizați API-ul Responses. Acesta oferă acces la cele mai recente funcționalități și la stocarea conversațiilor.
- Migrare de la OpenAI: începeți cu Chat Completions pentru a minimiza modificările de cod, apoi migrați treptat către API-ul Responses.
- Imagini sensibile: API-ul Responses cu
store: falsesau API-ul Chat Completions (fără stare prin natura sa).
Puncte cheie
- API-ul Responses utilizează
input_image+input_text, iar API-ul Chat Completions utilizeazăimage_url+text - Structura URL-ului diferă: direct în Responses, imbricat în Chat Completions
- API-ul Responses este alegerea recomandată pentru orice dezvoltare nouă
- Nu amestecați niciodată sintaxele ambelor API-uri în aceeași cerere
- Verificați întotdeauna tipul obiectului (
input_imagevsimage_url) pentru a evita erorile silențioase
Testați-vă cunoștințele
Viziunea API xAI: formate, tokeni, sintaxe – este totul la locul lui?
1. Cum trimiteți o imagine către API?
Răspuns: Prin URL sau Base64, într-un mesaj cu conținut mixt – respectând formatul și constrângerile de dimensiune documentate.
2. Ce controlează parametrul detail (auto, low, high)?
Răspuns: Granularitatea analizei și costul: low economisește tokeni pentru cazuri de utilizare grosiere, high maximizează precizia (OCR, detalii fine), iar auto lasă API-ul să decidă.
3. Cum se calculează costul unei imagini?
Răspuns: În tokeni de imagine – de la 256 la 1792, în funcție de rezoluție și detaliu: dimensionarea imaginilor și nivelul de detaliu reprezintă prima pârghie de optimizare.
4. Ce permite compararea mai multor imagini?
Răspuns: Trimiterea mai multor imagini într-o singură cerere și raționamentul asupra lor – diferențe, evoluții, consistență – fără nicio limită privind numărul de imagini per cerere.
5. input_image sau image_url: pe care să îl alegeți?
Răspuns: input_image este sintaxa modernă a API-ului Responses; image_url persistă ca moștenire Chat Completions – pentru codul nou, sintaxa modernă este obligatorie.
Format bun, detaliu bun, sintaxă bună: viziunea este pilotată ca textul – până la nivel de token.