Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Tiedostojen lataaminen Files API:n avulla

Oppitunti 1 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kopioi-liitä -menetelmästä natiiveihin dokumentteihin
  2. Ensimmäinen latauksesi
  3. Parametrit ja todennus
  4. Tiedoston käyttäminen
  5. Keskeiset asiat

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.

48 MB
Enimmäiskoko tiedostoa kohden
POST
HTTP-latausmenetelmä
$10
Per 1 000 kutsua
Auto
attachment_search-aktivointi

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, muodossa multipart/form-data
  • purpose-parametrin on oltava "assistants"
  • Palautettu file_id on viittauksesi kaikkiin myöhempiin operaatioihin
  • attachment_search-työkalu aktivoituu automaattisesti, kun tiedostoon viitataan pyynnössä
  • Kustannus on 10 dollaria per 1 000 liitekutsua