Salt la conținutul principal
Română— Alege o limbă
Meniu

Încărcarea fișierelor cu API-ul Files

Lecția 1 din 16 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. De la copiere-lipire la documente native
  2. Prima dumneavoastră încărcare
  3. Parametri și autentificare
  4. Utilizarea fișierului
  5. Puncte cheie

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.

48 MB
Dimensiune maximă per fișier
POST
Metodă de încărcare HTTP
$10
La 1.000 de apeluri
Auto
Activare attachment_search

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/files acceptă fișiere de până la 48 MB în format multipart/form-data
  • Parametrul purpose trebuie să fie "assistants"
  • file_id returnat este referința dumneavoastră pentru toate operațiunile ulterioare
  • Instrumentul attachment_search se 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