Fájlok feltöltése a Files API-val
Ezen az oldalon
Másolás-beillesztés helyett natív dokumentumok
Biztosan illesztettél már be tizenöt oldalnyi jelentést egy promptba, remélve, hogy a formázás megmarad. Sosem marad: az oszlopok összekeverednek, és a modell végül csak szöveges masszában tud gondolkodni. Az xAI Files API-ja pontosan ezt a problémát oldja meg. Elküldöd az eredeti dokumentumot, az xAI szerveroldalon elemzi, és a Grok olyan tartalommal dolgozik, ahol a szerkezet, a táblázatok és a szakaszelválasztók érintetlenek maradnak.
A mechanizmus egyetlen végpontra épül: POST /v1/files. A fájlt multipart/form-data formátumban küldöd el egy "assistants" értékű purpose paraméterrel, mire az API visszaad egy egyedi azonosítót, a file_id-t. Ez az azonosító lesz a kulcs minden további művelethez: a dokumentum lekérdezéséhez, a metaadatok ellenőrzéséhez, a törléshez vagy egy gyűjteményhez való hozzáadáshoz.
Az első feltöltésed
Vegyünk egy PDF formátumú éves jelentést, ami a meghajtódon várakozik. A feltöltési kérés nem JSON, hanem multipart/form-data, ami magyarázza a -d helyetti -F szintaxist:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
A válasz néhány másodperc alatt megérkezik, és tartalmazza a fájlazonosítót valamint annak jellemzőit:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Ez a file_id – jelen esetben a file_abc123xyz – a dokumentumod állandó hivatkozása. Jegyezd fel, amint megkapod a választ: egy elveszett azonosító egy árván maradt fájlt jelent, amely fogyasztja a kvótádat, de használhatatlan.
Paraméterek és hitelesítés
Csak két paraméter van, és mindkettő kötelező:
- file: A fájl bináris tartalma, multipartként elküldve. A maximális méret 48 MB.
- purpose: Mindig
"assistants", ez az egyetlen jelenleg elfogadott érték. Azt jelzi, hogy a fájlt modell-interakciókhoz használod majd.
Gyorsabban elérheted a 48 MB-os limitet, mint gondolnád: egy napos naplóexport vagy egy teljes termékdokumentáció rendszeresen meghaladja ezt. Ilyenkor bontsd fel a forrást több logikus fájlra, ahelyett, hogy önkényesen levágnád belőle – később mindet ugyanabban a gyűjteményben találod majd meg.
A hitelesítés oldalán minden Files API kérés magában foglalja a szabványos API-kulcsodat az Authorization: Bearer fejlécben. Jegyezd meg most rögtön, hogy ez a kulcs nem ugyanaz, mint a Management API Key: az utóbbit, amely a gyűjteményekhez szükséges, a tanfolyam későbbi részében tárgyaljuk, és a kezdeti kísérletek során gyakran összekeverik az elsővel.
A fájl használata
A feltöltött fájl haszontalan, hacsak nem hivatkozol rá egy kérésben. Ezt a feladatot látja el a Responses API input_file blokkja, amelyet egy szabad szöveges utasítással egészítesz ki:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Foglald össze ennek a dokumentumnak a legfontosabb pontjait."
}
]
}
A Grok megkapja a fájlt, automatikusan aktiválja szerveroldalon az attachment_search eszközt, kinyeri a releváns szakaszokat, és ezek alapján írja meg a választ. Nincs szükség manuális aktiválásra, és további paramétereket sem kell hozzáadni: egy input_file jelenléte elég ahhoz, hogy elindítsa az egész láncolatot. Minden csatolmányhívás díja 1000 hívásonként 10 USD, így egyetlen feltöltés tízszeri lekérdezése költséghatékonyabb, mint ugyanannak a dokumentumnak tíz külön feltöltése.
Árazás 2026. augusztus 5-i állapot szerint – az árak rendszeresen változnak: bármilyen költségvetés-számítás előtt ellenőrizd az aktuális díjszabást az xAI hivatalos modell- és árazási oldalán.
Főbb megállapítások
- A
POST /v1/filesvégpont legfeljebb 48 MB-os fájlokat fogad elmultipart/form-dataformátumban. - A
purposeparaméternek mindig"assistants"értékűnek kell lennie. - A visszaadott
file_ida hivatkozásod minden ezt követő művelethez. - Az
attachment_searcheszköz automatikusan aktiválódik, amikor egy fájlt hivatkozol egy kérésben. - A költség 1000 csatolmányhívásonként 10 USD.