Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Fájlok feltöltése a Files API-val

1. lecke 16 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Másolás-beillesztés helyett natív dokumentumok
  2. Az első feltöltésed
  3. Paraméterek és hitelesítés
  4. A fájl használata
  5. Főbb megállapítások

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.

48 MB
Maximális fájlméret
POST
HTTP feltöltési módszer
$10
1000 hívásonként
Auto
attachment_search aktiválás

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/files végpont legfeljebb 48 MB-os fájlokat fogad el multipart/form-data formátumban.
  • A purpose paraméternek mindig "assistants" értékűnek kell lennie.
  • A visszaadott file_id a hivatkozásod minden ezt követő művelethez.
  • Az attachment_search eszkö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.