Caricamento file con l'API Files
In questa pagina
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.
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/filesaccetta file fino a 48 MB inmultipart/form-data - Il parametro
purposedeve essere"assistants" - Il
file_idrestituito è il tuo riferimento per tutte le operazioni successive - Lo strumento
attachment_searchsi attiva automaticamente quando un file viene referenziato in una richiesta - Il costo è di $10 ogni 1.000 chiamate con allegati