Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Caricamento file con l'API Files

Lezione 1 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Dal copia-incolla ai documenti nativi
  2. Il tuo primo upload
  3. Parametri e autenticazione
  4. Utilizzo del file
  5. Punti chiave

Dal copia-incolla ai documenti nativi

Probabilmente hai già incollato quindici pagine di un report in un prompt, sperando che il layout sopravviva. Non succede mai: le colonne delle tabelle si mescolano e il modello finisce per ragionare su un ammasso di testo informe. L’API Files di xAI risolve esattamente questo problema. Invii il documento originale, xAI lo analizza lato server e Grok lavora sul contenuto preservando struttura, tabelle e interruzioni di sezione.

Il meccanismo si riduce a un singolo endpoint, POST /v1/files. Invii il tuo file come multipart/form-data con un parametro purpose impostato su "assistants"; l’API restituisce un identificativo univoco chiamato file_id. Questo identificativo diventa la chiave per tutte le operazioni successive: interrogare il documento, verificarne i metadati, eliminarlo o aggiungerlo a una collezione.

48 MB
Dimensione massima per file
POST
Metodo di upload HTTP
$10
Ogni 1.000 chiamate
Auto
Attivazione di attachment_search

Il tuo primo upload

Prendi un rapporto annuale in formato PDF salvato sul tuo drive. La richiesta di upload non è in JSON ma in multipart/form-data, il che spiega l’uso della sintassi -F invece di -d:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

La risposta arriva in pochi secondi e contiene l’identificativo del file insieme alle sue caratteristiche:

{
  "id": "file_abc123xyz",
  "object": "file",
  "bytes": 2458901,
  "created_at": 1710000000,
  "filename": "annual-report.pdf",
  "purpose": "assistants"
}

Questo file_id—qui file_abc123xyz—è il tuo riferimento permanente al documento. Annotalo non appena ricevi la risposta: un identificativo perso significa un file orfano che consuma quota senza essere utilizzabile.

Parametri e autenticazione

Solo due parametri, entrambi obbligatori:

  • file: Il contenuto binario del file, inviato come multipart. La dimensione massima è 48 MB
  • purpose: Sempre "assistants", l’unico valore accettato finora. Indica che il file sarà utilizzato per le interazioni con il modello

Raggiungerai il limite di 48 MB più velocemente di quanto pensi: un’esportazione dei log di una giornata o la documentazione completa di un prodotto lo superano regolarmente. In questo caso, dividi la sorgente in diversi file coerenti invece di troncarla arbitrariamente: li ritroverai tutti nella stessa collezione in seguito.

Per quanto riguarda l’autenticazione, ogni richiesta all’API Files include la tua chiave API standard nell’intestazione Authorization: Bearer. Tieni presente fin da ora che questa chiave non è la Management API Key: quest’ultima, riservata alle collezioni, verrà trattata più avanti nel corso e viene spesso confusa con la prima durante i primi tentativi.

Utilizzo del file

Il file caricato è inutile se non vi fai riferimento in una richiesta. È questo il ruolo del blocco input_file nell’API Responses, che accompagni con un’istruzione in testo libero:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123xyz"
    },
    {
      "type": "input_text",
      "text": "Riassumi i punti chiave di questo documento."
    }
  ]
}

Grok riceve il file, attiva automaticamente lo strumento attachment_search lato server, estrae i passaggi rilevanti e scrive la sua risposta basandosi su di essi. Non è necessaria alcuna attivazione manuale e non serve aggiungere parametri aggiuntivi: la presenza di un input_file è sufficiente a innescare l’intera catena. Ogni chiamata con allegato viene fatturata a $10 per 1.000, rendendo un singolo upload interrogato dieci volte più conveniente rispetto a dieci upload dello stesso documento.

Prezzi aggiornati al 5 agosto 2026 — i prezzi cambiano regolarmente: prima di qualsiasi calcolo di budget, verifica la griglia attuale sulla pagina ufficiale dei modelli e dei prezzi di xAI.

Punti chiave

  • L’endpoint POST /v1/files accetta file fino a 48 MB in multipart/form-data
  • Il parametro purpose deve essere "assistants"
  • Il file_id restituito è il tuo riferimento per tutte le operazioni successive
  • Lo strumento attachment_search si attiva automaticamente quando un file viene referenziato in una richiesta
  • Il costo è di $10 ogni 1.000 chiamate con allegati