Vai al contenuto principale
Italiano— Scegli una lingua
Menu

input_image vs image_url: le due sintassi

Lezione 12 di 12 Aggiornata il 30 luglio 2026 Principiante
In questa pagina
  1. Due API, due sintassi
  2. API Responses: input_image (consigliato)
  3. API Chat Completions: image_url (legacy)
  4. Tabella comparativa
  5. Errori di sintassi comuni
  6. Quando usare quale API
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

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 (non image_url)
  • L’URL o il Data URI va direttamente in image_url (nessun oggetto annidato)
  • detail si trova allo stesso livello di image_url
  • Il testo utilizza il tipo input_text
  • L’array input sostituisce l’array messages delle 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 (non input_image)
  • L’URL si trova in un oggetto annidato image_url.url (doppio annidamento)
  • detail risiede all’interno dell’oggetto image_url
  • Il testo utilizza il tipo text (non input_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: false o API Chat Completions (stateless per natura).

Punti chiave

  • L’API Responses usa input_image + input_text, l’API Chat Completions usa image_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_image vs image_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.