input_image vs image_url: le due sintassi
In questa pagina
Due API, due sintassi
xAI offre due endpoint per interagire con Grok e ciascuno utilizza una sintassi diversa per l’invio delle immagini. Comprendere queste differenze è essenziale per scrivere codice corretto ed evitare errori frustranti.
API Responses: input_image (consigliato)
L’API Responses è il nuovo endpoint principale di xAI. Le nuove funzionalità vengono aggiunte qui per prime. Questa è l’API da privilegiare per qualsiasi nuovo progetto.
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."
}
]
}
Caratteristiche
- Il tipo è
input_image(nonimage_url) - L’URL o il Data URI va direttamente in
image_url(nessun oggetto annidato) detailsi trova allo stesso livello diimage_url- Il testo utilizza il tipo
input_text - L’array
inputsostituisce l’arraymessagesdelle 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 Chat Completions: image_url (legacy)
L’API Chat Completions è l’endpoint legacy, mantenuto per compatibilità con gli SDK OpenAI esistenti. Se stai migrando codice scritto per OpenAI, questa API facilita la transizione.
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."
}
]
}
]
}
Caratteristiche
- Il tipo è
image_url(noninput_image) - L’URL si trova in un oggetto annidato
image_url.url(doppio annidamento) detailrisiede all’interno dell’oggettoimage_url- Il testo utilizza il tipo
text(noninput_text) - I messaggi hanno un
role(system, user, assistant)
Python con 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)
Tabella comparativa
| Aspect | API Responses | Chat Completions |
|---|---|---|
| Status | Primary (recommended) | Legacy (compatibility) |
| Image type | input_image | image_url |
| Text type | input_text | text |
| Image URL | image_url: "..." | image_url.url: "..." |
| State management | Stateful (previous_response_id) | Stateless (resend everything) |
| Storage | store: true/false | No (stateless) |
| Server tools | web_search, x_search, code_interpreter | Limited |
Errori di sintassi comuni
Errore 1: Mescolare i formati
# SBAGLIATO — Sintassi Chat Completions nell'API Responses
input=[
{"type": "image_url", "image_url": {"url": "..."}} # No!
]
# CORRETTO — Sintassi API Responses
input=[
{"type": "input_image", "image_url": "..."} # Sì!
]
Errore 2: Dimenticare la struttura annidata in Chat Completions
# SBAGLIATO — URL diretto in Chat Completions
{"type": "image_url", "image_url": "https://..."} # No!
# CORRETTO — Oggetto annidato
{"type": "image_url", "image_url": {"url": "https://..."}} # Sì!
Errore 3: Usare “text” invece di “input_text”
# SBAGLIATO — Tipo "text" nell'API Responses
input=[
{"type": "text", "text": "Describe."} # No!
]
# CORRETTO
input=[
{"type": "input_text", "text": "Describe."} # Sì!
]
Quando usare quale API
- Nuovo progetto: usa l’API Responses. Ti dà accesso alle ultime funzionalità e all’archiviazione delle conversazioni.
- Migrazione da OpenAI: inizia con Chat Completions per minimizzare le modifiche al codice, poi migra gradualmente all’API Responses.
- Immagini sensibili: API Responses con
store: falseo API Chat Completions (stateless per natura).
Punti chiave
- L’API Responses usa
input_image+input_text, l’API Chat Completions usaimage_url+text - La struttura dell’URL differisce: diretta in Responses, annidata in Chat Completions
- L’API Responses è la scelta raccomandata per tutto il nuovo sviluppo
- Non mescolare mai le sintassi di entrambe le API nella stessa richiesta
- Controlla sempre il tipo di oggetto (
input_imagevsimage_url) per evitare errori silenziosi
Metti alla prova le tue conoscenze
API vision di xAI: formati, token, sintassi: è tutto a posto?
1. Come si invia un'immagine all'API?
Risposta: Tramite URL o Base64, in un messaggio a contenuto misto, rispettando il formato documentato e i vincoli di dimensione.
2. Cosa controlla il parametro detail (auto, low, high)?
Risposta: La granularità dell’analisi e il costo: low risparmia token per casi d’uso grossolani, high massimizza la precisione (OCR, dettagli fini), auto lascia decidere all’API.
3. Come viene calcolato il costo di un'immagine?
Risposta: In token immagine, da 256 a 1792 a seconda della risoluzione e del dettaglio: dimensionare le immagini e il livello di dettaglio è la prima leva di ottimizzazione.
4. Cosa abilita il confronto multi-immagine?
Risposta: L’invio di più immagini in una singola richiesta e il ragionamento su di esse (differenze, evoluzioni, coerenza), senza limiti sul numero di immagini per richiesta.
5. input_image o image_url: quale scegliere?
Risposta: input_image è la sintassi moderna dell’API Responses; image_url persiste come legacy di Chat Completions: per il nuovo codice, la sintassi moderna è obbligatoria.
Buon formato, buon dettaglio, buona sintassi: la visione si pilota come il testo, fino al token.