Dodawanie żądań w formacie JSON
Na tej stronie
Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji xAI: rabat na partie wynosi 20% dla kwalifikujących się modeli tekstowych (a nie 50%), przykłady korzystają z interfejsu REST API oraz oficjalnego
xai-sdk(client.batch.*; Batch API od xAI nie używa formatu OpenAI, więc SDK OpenAI nie ma zastosowania), a Responses API ma pierwszeństwo przed Chat Completions, które są przestarzałym punktem końcowym w xAI. Źródła: Batch API · REST Reference · Batch Pricing.
Dodawanie przez API
Po utworzeniu partii dodajesz do niej żądania, wysyłając żądanie POST /v1/batches/{batch_id}/requests. Każde wywołanie przenosi listę żądań i możesz wywoływać ten punkt końcowy tyle razy, ile potrzebujesz, dopóki partia nie zostanie anulowana. To podejście sprawdza się w przypadku partii budowanych przyrostowo.
Struktura żądania
Treść wywołania zawiera tablicę batch_requests. Każdy element łączy identyfikator (batch_request_id) z samym żądaniem, przechowywanym pod kluczem odpowiadającym jego typowi – responses dla Responses API:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
{"role": "user", "content": "The product exceeded my expectations!"}
]
}
}
}
]
}
batch_request_id: Twój identyfikator, unikalny w obrębie partii. To klucz łączący żądanie z jego wynikiem; jeśli go brakuje, xAI generuje UUID.batch_request: Żądanie umieszczone pod kluczem odpowiadającym jego typowi; dokumentacja API wspomina również ochat_get_completiondla formatu Chat Completions.
W przypadku obrazów i wideo użyj SDK (lekcja 9) lub pliku JSONL (następna lekcja).
Żądanie cURL
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_requests": [
{
"batch_request_id": "article-42",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "user", "content": "Classify this text: positive, neutral, or negative."}
]
}
}
}
]
}'
Dodawanie za pomocą Python SDK
Korzystając z SDK, każde żądanie budujesz jak standardową rozmowę, przypisując mu batch_request_id, a następnie dodajesz je partiami:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "First document to analyze..."},
{"id": "doc-2", "text": "Second document to analyze..."},
{"id": "doc-3", "text": "Third document to analyze..."},
]
batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"
requests = []
for doc in documents:
chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
chat.append(system("Summarize the document in two sentences."))
chat.append(user(doc["text"]))
requests.append(chat)
# Dodawaj partiami po 100: jedno wywołanie API na partię
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentacja nie określa maksymalnej liczby żądań na jedno wywołanie; umiarkowane rozmiary partii po prostu ograniczają ilość danych, które trzeba resendować w przypadku awarii sieci.
Limity szybkości dodawania
Zespół może wykonać do 1000 wywołań dodawania co 30 sekund w przesuwnym oknie wspólnym dla wszystkich jego partii. Limit dotyczy wywołań, a nie żądań: przy partiach po 100 żądań pozwala to już na przetworzenie ponad 3000 żądań na sekundę. Istotne są jeszcze dwa inne ograniczenia:
- Maksymalnie 25 MB na pojedyncze żądanie, co dotyczy głównie obrazów zakodowanych w base64.
- Po przekroczeniu 100 000 żądań w partii, xAI może spowolnić przetwarzanie, aby zachować stabilność usługi.
Kiedy używać dodawania przez API
Dodawanie przez API sprawdza się zawsze, gdy elastyczność jest ważniejsza niż wstępne przygotowanie. Staje się naturalnym wyborem, gdy partia jest budowana przyrostowo: żądania napływające z kolejki są dodawane na bieżąco, podczas gdy plik JSONL wymagałby znajomości wszystkich danych z góry – i zamknąłby partię. To także właściwa ścieżka do prototypowania, aby przetestować pełny przepływ pracy na pięciu żądaniach przed skalowaniem, oraz dla partii heterogenicznych.
Walidacja żądań
Sprawdzaj kod statusu każdego wywołania dodawania: błąd na tym etapie oznacza, że partia nie została zapisana i musisz ją wysłać ponownie. Żądanie może też nie powieść się później, podczas przetwarzania; wtedy pojawi się w wynikach wraz z komunikatem o błędzie. Model, który nie akceptuje partii, zostanie odrzucony z komunikatem not supported for batch processing: przed uruchomieniem dużej partii sprawdź kwalifikowalność na stronie modelu.
Kluczowe wnioski
- Dodawanie odbywa się przez
POST /v1/batches/{id}/requestsz listąbatch_requests. - Każde żądanie zawiera unikalny
batch_request_idoraz swoją treść pod kluczem odpowiadającym typowi (responses,chat_get_completion). - SDK buduje żądania za pomocą
client.chat.create(..., batch_request_id=...)i dodaje je przezclient.batch.add. - Limit wynosi 1000 wywołań dodawania na 30 sekund dla zespołu; każde wywołanie może przenosić wiele żądań.
- W przeciwieństwie do pliku JSONL, dodawanie przez API pozostawia partię otwartą na nowe elementy.