Přidávání požadavků v JSON
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace xAI: sleva pro dávkové zpracování činí 20 % u způsobilých textových modelů (nikoli 50 %), příklady se řídí REST API a oficiálním
xai-sdk(client.batch.*; Batch API od xAI nepoužívá formát OpenAI, SDK OpenAI se tedy neaplikuje) a API Responses má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · REST Reference · Batch Pricing.
Přidávání přes API
Jakmile je dávka vytvořena, přidáš do ní požadavky pomocí POST /v1/batches/{batch_id}/requests. Každý volání nese seznam požadavků a koncový bod můžeš volat opakovaně, dokud není dávka zrušena. Tento přístup funguje pro dávky budované postupně.
Struktura požadavku
Tělo volání obsahuje pole batch_requests. Každý prvek spojuje identifikátor (batch_request_id) se samotným požadavkem, který je uložen pod klíčem odpovídajícím jeho typu – responses pro API Responses:
{
"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: Tvůj identifikátor, jedinečný v rámci dávky. Toto je klíč, který spojuje požadavek s jeho výsledkem; pokud chybí, xAI vygeneruje UUID.batch_request: Požadavek pod klíčem odpovídajícím jeho typu; reference API dokumentuje takéchat_get_completionpro formát Chat Completions.
Pro obrázky a videa použij SDK (lekce 9) nebo soubor JSONL (další lekce).
Požadavek 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."}
]
}
}
}
]
}'
Přidávání pomocí Python SDK
Při práci se SDK vytvoříš každý požadavek jako běžnou konverzaci, přiřadíš mu batch_request_id a následně je přidáváš po blocích:
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)
# Přidání po blocích po 100: jedno volání API na blok
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentace nestanovuje maximální počet požadavků na jedno volání; mírná velikost bloků pouze omezuje množství dat, která je třeba znovu odeslat v případě výpadku sítě.
Limity rychlosti při přidávání
Tým může provést až 1 000 volání pro přidání každých 30 sekund v pohyblivém okně sdíleném mezi všemi jeho dávkami. Limit se týká volání, nikoli jednotlivých požadavků: při blocích po 100 požadavcích to již umožňuje více než 3 000 požadavků za sekundu. Důležitější jsou však další dvě omezení:
- 25 MB maximum pro jednotlivý požadavek, což se týká především obrázků kódovaných v base64.
- Při překročení 100 000 požadavků v jedné dávce může xAI zpomalit zpracování, aby zachovala stabilitu služby.
Kdy použít přidávání přes API
Přidávání přes API se hodí vždy, když je flexibilita důležitější než příprava předem. Stává se přirozenou volbou, když je dávka budována postupně: požadavky přicházející z fronty se přidávají, jakmile dorazí, zatímco soubor JSONL by vyžadoval znalost všech dat předem – a dávku by uzavřel. Je to také správná cesta pro prototypování, kdy chceš otestovat celý pracovní postup s pěti požadavky před jejich navýšením, a pro heterogenní dávky.
Validace požadavků
Zkontroluj stavový kód každého volání pro přidání: chyba v této fázi znamená, že blok nebyl uložen, a musíš jej znovu odeslat. Požadavek může také selhat později, během zpracování; v takovém případě se objeví ve výsledcích spolu se svou chybovou zprávou. Model, který nepřijímá dávkové zpracování, bude odmítnut se zprávou not supported for batch processing: před spuštěním velké dávky si ověř způsobilost na stránce modelu.
Klíčové poznatky
- Přidávání probíhá přes
POST /v1/batches/{id}/requestsse seznamembatch_requests. - Každý požadavek nese jedinečné
batch_request_ida svůj obsah pod klíčem odpovídajícím typu (responses,chat_get_completion). - SDK vytváří požadavky pomocí
client.chat.create(..., batch_request_id=...)a přidává je přesclient.batch.add. - Limit pro tým činí 1 000 volání pro přidání každých 30 sekund, přičemž každé volání může nést mnoho požadavků.
- Na rozdíl od souboru JSONL ponechává přidávání přes API dávku otevřenou pro další doplňování.