Przejdź do głównej treści
Polski— Wybierz język
Menu

Przesyłanie plików za pomocą Files API

Lekcja 1 z 16 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Od kopiowania i wklejania do natywnych dokumentów
  2. Twoje pierwsze przesłanie pliku
  3. Parametry i uwierzytelnianie
  4. Używanie pliku
  5. Kluczowe wnioski

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.

48 MB
Maksymalny rozmiar pliku
POST
Metoda przesyłania HTTP
$10
Za 1000 wywołań
Auto
Aktywacja attachment_search

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/files przyjmuje pliki do 48 MB w formacie multipart/form-data
  • Parametr purpose musi mieć wartość "assistants"
  • Zwracany file_id jest Twoim odniesieniem do wszystkich kolejnych operacji
  • Narzędzie attachment_search aktywuje się automatycznie, gdy plik zostanie użyty w żądaniu
  • Koszt wynosi 10 USD za 1000 wywołań z załącznikiem