Przesyłanie plików za pomocą Files API
Na tej stronie
Od kopiowania i wklejania do natywnych dokumentów
Pewnie już zdarzyło Ci się wkleić do promptu piętnaście stron raportu, licząc, że układ strony się zachowa. Nigdy to nie działa: kolumny tabel mieszają się, a model kończy wnioskowanie na podstawie tekstowej papki. Files API od xAI rozwiązuje dokładnie ten problem. Wysyłasz oryginalny dokument, xAI analizuje go po stronie serwera, a Grok pracuje na treści, w której zachowana jest struktura, tabele i podziały sekcji.
Mechanizm sprowadza się do jednego punktu końcowego: POST /v1/files. Wysyłasz plik jako multipart/form-data z parametrem purpose ustawionym na "assistants", a API zwraca unikalny identyfikator zwany file_id. Ten identyfikator staje się kluczem do wszystkich kolejnych działań: odpytywania dokumentu, sprawdzania jego metadanych, usuwania go lub dodawania do kolekcji.
Twoje pierwsze przesłanie pliku
Weź raport roczny w formacie PDF leżący na dysku. Żądanie przesłania nie jest w formacie JSON, lecz multipart/form-data, co wyjaśnia użycie składni -F zamiast -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Odpowiedź przychodzi w ciągu kilku sekund i zawiera identyfikator pliku wraz z jego charakterystyką:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
To file_id – w tym przypadku file_abc123xyz – jest Twoim stałym odniesieniem do dokumentu. Zapisz je natychmiast po otrzymaniu odpowiedzi: utracony identyfikator oznacza osierocony plik, który zużywa limit, ale nie nadaje się do użytku.
Parametry i uwierzytelnianie
Tylko dwa parametry, oba wymagane:
- file: Binarna zawartość pliku wysyłana jako multipart. Maksymalny rozmiar to 48 MB
- purpose: Zawsze
"assistants", jedyna obecnie akceptowana wartość. Wskazuje, że plik będzie używany do interakcji z modelem
Szybciej niż myślisz, natkniesz się na limit 48 MB: eksport logów z jednego dnia lub kompletna dokumentacja produktu regularnie go przekraczają. W takim przypadku podziel źródło na kilka spójnych plików zamiast arbitralnie je przycinać – później i tak znajdziesz je wszystkie w tej samej kolekcji.
Jeśli chodzi o uwierzytelnianie, każde żądanie do Files API niesie Twój standardowy klucz API w nagłówku Authorization: Bearer. Miej teraz na uwadze, że ten klucz to nie Management API Key: ten drugi, zarezerwowany dla kolekcji, pojawi się później w kursie i na początkowych etapach często myli się go z tym pierwszym.
Używanie pliku
Przesłany plik jest bezużyteczny, jeśli nie odwołasz się do niego w żądaniu. Tę rolę pełni blok input_file w Responses API, któremu towarzyszy instrukcja w postaci wolnego tekstu:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Podsumuj kluczowe punkty tego dokumentu."
}
]
}
Grok otrzymuje plik, automatycznie aktywuje po stronie serwera narzędzie attachment_search, wydobywa odpowiednie fragmenty i na ich podstawie generuje odpowiedź. Nie trzeba nic aktywować ręcznie ani dodawać dodatkowych parametrów: sama obecność input_file wystarczy, by uruchomić cały łańcuch. Każde wywołanie z załącznikiem kosztuje 10 USD za 1000 wywołań, co sprawia, że pojedyncze przesłanie odpytane dziesięciokrotnie jest bardziej opłacalne niż dziesięciokrotne przesyłanie tego samego dokumentu.
Cennik na dzień 5 sierpnia 2026 r. – ceny zmieniają się regularnie: przed jakimkolwiek obliczeniem budżetu sprawdź aktualny cennik na oficjalnej stronie modeli i cennika xAI.
Kluczowe wnioski
- Punkt końcowy
POST /v1/filesprzyjmuje pliki do 48 MB w formaciemultipart/form-data - Parametr
purposemusi mieć wartość"assistants" - Zwracany
file_idjest Twoim odniesieniem do wszystkich kolejnych operacji - Narzędzie
attachment_searchaktywuje się automatycznie, gdy plik zostanie użyty w żądaniu - Koszt wynosi 10 USD za 1000 wywołań z załącznikiem