Încărcarea fișierelor cu API-ul Files
Pe această pagină
De la copiere-lipire la documente native
Probabil ați lipit deja cincisprezece pagini dintr-un raport într-un prompt, sperând că formatarea se va păstra. Nu se întâmplă niciodată: coloanele tabelelor se amestecă, iar modelul ajunge să raționeze pe baza unui text inform. API-ul Files de la xAI rezolvă exact această problemă. Trimiteți documentul original, xAI îl analizează lato-server, iar Grok lucrează pe conținut unde structura, tabelele și separatoarele de secțiuni sunt păstrate intacte.
Mecanismul se integrează într-un singur endpoint, POST /v1/files. Trimiteți fișierul ca multipart/form-data cu un parametru purpose setat la "assistants", iar API-ul returnează un identificator unic numit file_id. Acest identificator devine cheia pentru tot ce faceți ulterior: interogarea documentului, verificarea metadatelor, ștergerea acestuia sau adăugarea lui într-o colecție.
Prima dumneavoastră încărcare
Luați un raport anual în format PDF aflat pe discul dumneavoastră. Cererea de încărcare nu este JSON, ci multipart/form-data, ceea ce explică sintaxa -F în loc de -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Răspunsul sosește în câteva secunde și conține identificatorul fișierului împreună cu caracteristicile sale:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Acest file_id—aici file_abc123xyz—este referința dumneavoastră permanentă pentru document. Notați-l imediat ce primiți răspunsul: un identificator pierdut înseamnă un fișier orfan care consumă cotă fără a putea fi utilizat.
Parametri și autentificare
Doi parametri, ambii obligatorii:
- file: Conținutul binar al fișierului, trimis ca multipart. Dimensiunea maximă este de 48 MB
- purpose: Întotdeauna
"assistants", singura valoare acceptată până în prezent. Indică faptul că fișierul va fi utilizat pentru interacțiuni cu modelul
Veți atinge limita de 48 MB mai repede decât vă așteptați: un export de jurnale pe o singură zi sau documentația completă a unui produs depășesc adesea această valoare. În acest caz, divizați sursa în mai multe fișiere coerente, în loc să le trunchiați arbitrar; le veți regăsi pe toate în aceeași colecție mai târziu.
În ceea ce privește autentificarea, fiecare cerere către API-ul Files include cheia API standard în antetul Authorization: Bearer. Rețineți chiar acum că această cheie nu este Management API Key: aceea, rezervată colecțiilor, va fi abordată mai târziu în curs și este adesea confundată cu prima în timpul primelor încercări.
Utilizarea fișierului
Fișierul încărcat este inutil dacă nu îl referenciați într-o cerere. Acesta este rolul blocului input_file din API-ul Responses, pe care îl însoțiți de o instrucțiune în text liber:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Summarize the key points of this document."
}
]
}
Grok primește fișierul, activează automat instrumentul attachment_search lato-server, extrage pasajele relevante și își scrie răspunsul pe baza lor. Nu este necesară nicio activare manuală și nu trebuie adăugați parametri suplimentari: prezența unui input_file este suficientă pentru a declanșa întregul lanț. Fiecare apel de atașament este facturat cu 10 USD la 1.000 de apeluri, ceea ce face ca o singură încărcare interogată de zece ori să fie mai eficientă din punct de vedere al costurilor decât zece încărcări ale aceluiași document.
Prețuri la data de 5 august 2026 — prețurile se modifică regulat: înainte de orice calcul bugetar, verificați grila actualizată pe pagina oficială a modelelor și prețurilor xAI.
Puncte cheie
- Endpoint-ul
POST /v1/filesacceptă fișiere de până la 48 MB în formatmultipart/form-data - Parametrul
purposetrebuie să fie"assistants" file_idreturnat este referința dumneavoastră pentru toate operațiunile ulterioare- Instrumentul
attachment_searchse activează automat când un fișier este referențiat într-o cerere - Costul este de 10 USD la 1.000 de apeluri de atașament