Tiedostojen lataaminen Files API:n avulla
Tällä sivulla
Kopioi-liitä -menetelmästä natiiveihin dokumentteihin
Olet todennäköisesti liittänyt kehotteeseen viisitoista sivua raporttia toivoen, että asettelu säilyy. Näin ei koskaan käy: taulukon sarakkeet sekaisin ja malli päätyy päättelyn tekemiseen tekstisössöstä. xAI:n Files API ratkaisee juuri tämän ongelman. Lähetät alkuperäisen dokumentin, xAI analysoi sen palvelinpuolella, ja Grok työskentelee sisällön parissa siten, että rakenne, taulukot ja osioiden väliset katkokset säilyvät.
Mekanismi mahtuu yhteen päätepisteeseen: POST /v1/files. Lähetät tiedostosi muodossa multipart/form-data mukana olevalla purpose-parametrilla, jonka arvoksi on asetettu "assistants", ja API palauttaa yksilöllisen tunnisteen nimeltä file_id. Tästä tunnisteesta tulee avain kaikkeen, mitä teet seuraavaksi: dokumentin kyselyyn, sen metatietojen tarkistamiseen, poistamiseen tai kokoelmaan lisäämiseen.
Ensimmäinen latauksesi
Ota ajoneuvosi kovalevyllä oleva vuosikertomus PDF-muodossa. Latauspyyntö ei ole JSON-muotoinen vaan multipart/form-data, mikä selittää -F-syntaksin käytön -d:n sijaan:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Vastaus saapuu muutamassa sekunnissa ja sisältää tiedostotunnisteen sekä sen ominaisuudet:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Tämä file_id – tässä tapauksessa file_abc123xyz – on pysyvä viittauksesi dokumenttiin. Kirjoita se muistiin heti vastauksen saatuasi: kadonnut tunniste tarkoittaa hylättyä tiedostoa, joka kuluttaa kiintiötä olematta käytettävissä.
Parametrit ja todennus
Vain kaksi parametria, molemmat pakollisia:
- file: Tiedoston binäärinen sisältö, lähetetty multipart-muodossa. Enimmäiskoko on 48 Mt.
- purpose: Aina
"assistants", ainoa tähän mennessä hyväksytty arvo. Se ilmoittaa, että tiedostoa käytetään mallivuorovaikutuksiin.
Kohtaat 48 Mt:n rajan nopeammin kuin arvaatkaan: yhden päivän lokivienti tai täydellinen tuotedokumentaatio ylittävät sen säännöllisesti. Tällöin jaa lähteesi useampaan loogiseen tiedostoon mieluummin kuin katkaiset sitä mielivaltaisesti – löydät ne myöhemmin kaikki samasta kokoelmasta.
Todennuksen osalta jokainen Files API:n pyyntö sisältää vakio-API-avaimesi Authorization: Bearer -otsikossa. Pidä mielessäsi jo nyt, että tämä avain ei ole Management API Key: se, joka on varattu kokoelmille, tulee kurssilla myöhemmin, ja sitä sekoitetaan usein ensimmäiseen alkuvaiheen yrityksissä.
Tiedoston käyttäminen
Ladattu tiedosto on hyödytön, ellei siihen viitata pyynnössä. Tämä on Responses API:n input_file-lohkon tehtävä, jonka yhteydessä annat vapaan tekstin muotoisen ohjeen:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Summarize the key points of this document."
}
]
}
Grok vastaanottaa tiedoston, aktivoi automaattisesti attachment_search-työkalun palvelinpuolella, poimii asiaankuuluvat kohdat ja kirjoittaa vastauksensa niiden perusteella. Manuaalista aktivointia ei tarvita, eikä lisäparametreja tarvitse lisätä: input_file:n olemassaolo riittää käynnistämään koko ketjun. Jokainen liitekutsu hinnoitellaan 10 dollarilla per 1 000 kutsua, mikä tekee yhdestä latauksesta, jota kysytään kymmenen kertaa, kustannustehokkaamman kuin kymmenen saman dokumentin latausta.
Hinnoittelu 5. elokuuta 2026 alkaen – hinnat muuttuvat säännöllisesti: ennen budjettilaskelmia tarkista nykyinen hinnasto xAI:n viralliselta mallit ja hinnoittelu -sivulta.
Keskeiset asiat
POST /v1/files-päätepiste hyväksyy tiedostoja, joiden koko on enintään 48 Mt, muodossamultipart/form-datapurpose-parametrin on oltava"assistants"- Palautettu
file_idon viittauksesi kaikkiin myöhempiin operaatioihin attachment_search-työkalu aktivoituu automaattisesti, kun tiedostoon viitataan pyynnössä- Kustannus on 10 dollaria per 1 000 liitekutsua