Kérések hozzáadása JSON-ban
Ezen az oldalon
Frissítve: 2026. november 2. az xAI dokumentációja alapján: a kötegelt kedvezmény 20% a jogosult szöveges modelleknél (nem 50%), a példák a REST API-t és a hivatalos
xai-sdk-t (client.batch.*) követik (az xAI Batch API nem az OpenAI formátumot használja, az OpenAI SDK nem alkalmazható), és a Responses API elsőbbséget élvez a Chat Completions felett, amely az xAI-nál már elavult végpont. Források: Batch API · REST Referencia · Batch Árazás.
Hozzáadás az API-n keresztül
Miután létrehoztad a köteget, a POST /v1/batches/{batch_id}/requests végponttal adhatsz hozzá kéréseket. Minden hívás egy kérésekkel teli listát tartalmaz, és addig hívhatod meg a végpontot, ahányszor csak szükséges, amíg a köteget nem mondták le. Ez a megközelítés az inkrementálisan felépített kötegeknél működik.
Kérés szerkezete
A hívás törzse egy batch_requests tömböt tartalmaz. Minden elem egy azonosítót (batch_request_id) párosít magával a kéréssel, amely a típusának megfelelő kulcs alatt található – a Responses API esetén ez a 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: A te azonosítód, amely egyedi kell legyen a kötegen belül. Ez a kulcs kapcsolja össze a kérést az eredménnyel; ha hiányzik, az xAI generál egy UUID-t.batch_request: Maga a kérés, a típusának megfelelő kulcs alatt; az API-referencia achat_get_completionkulcsot is dokumentálja a Chat Completions formátumhoz.
Képek és videók esetén használd az SDK-t (9. lecke) vagy egy JSONL fájlt (következő lecke).
cURL kérés
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."}
]
}
}
}
]
}'
Hozzáadás a Python SDK-val
Az SDK segítségével minden kérést egy szabványos beszélgetésként építesz fel, hozzárendelsz egy batch_request_id-t, majd csoportokban adod hozzá őket:
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)
# Hozzáadás 100-as csoportokban: egy API-hívás csoportonként
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
A dokumentáció nem határoz meg maximális kérésszámot hívásonként; a mérsékelt csoportméretek egyszerűen korlátozzák azt a mennyiséget, amelyet hálózati hiba esetén újra kell küldeni.
Hozzáadási sebességkorlátok
Egy csapat legfeljebb 1000 hozzáadó hívást indíthat 30 másodpercenként, egy csúszó ablakban, amely az összes kötegére érvényes. A korlát a hívásokra vonatkozik, nem a kérésekre: 100 kérésből álló csoportok esetén ez már másodpercenként több mint 3000 kérést tesz lehetővé. Két másik korlát azonban fontosabb:
- 25 MB maximális méret egyedi kérésenként, ami főleg a base64-ben kódolt képeket érinti
- 100 000 kérés felett egy kötegen belül az xAI lassíthatja a feldolgozást a szolgáltatás stabilitásának megőrzése érdekében
Mikor használd az API-s hozzáadást?
Az API-s hozzáadás akkor működik jól, amikor a rugalmasság fontosabb, mint az előzetes előkészítés. Természetes választássá válik, amikor a köteget inkrementálisan építed fel: a sorból érkező kéréseket beérkezésükkor adod hozzá, míg egy JSONL fájl megkövetelné, hogy előre ismerj mindent – és lezárná a köteget. Ez az út a prototípus-készítéshez is, hogy öt kéréssel teszteld a teljes munkafolyamatot a skálázás előtt, valamint vegyes összetételű kötegeknél.
Kérésérvényesítés
Ellenőrizd minden hozzáadó hívás állapotkódját: egy ilyen hiba azt jelenti, hogy a csoportot nem mentette el a rendszer, és újra el kell küldened. Egy kérés később, feldolgozás közben is sikertelen lehet; ekkor a hibaüzenetével együtt jelenik meg az eredmények között. Ha egy modell nem fogadja el a köteget, a rendszer a not supported for batch processing üzenettel utasítja el: a nagy köteg indítása előtt ellenőrizd a jogosultságot a modell oldalán.
Főbb megállapítások
- A hozzáadás a
POST /v1/batches/{id}/requestsvégponton történik, egybatch_requestslistával - Minden kérés tartalmaz egy egyedi
batch_request_id-t és a tartalmát a típusának megfelelő kulcs alatt (responses,chat_get_completion) - Az SDK a
client.chat.create(..., batch_request_id=...)segítségével építi fel a kéréseket, és aclient.batch.addmetódussal adja hozzá őket - A korlát csapatonként 1000 hozzáadó hívás 30 másodpercenként, ahol minden hívás sok kérést hordozhat
- A JSONL fájllal ellentétben az API-s hozzáadás nyitva hagyja a köteget az új elemek számára