Dodavanje zahtjeva u JSON-u
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za batch iznosi 20 % na kvalificirane tekstualne modele (ne 50 %), primjeri slijede REST API i službeni
xai-sdk(client.batch.*; xAI Batch API ne koristi OpenAI format, OpenAI SDK se ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST referenca · Cjenik za Batch.
Dodavanje putem API-ja
Nakon što stvoriš batch, dodaješ mu zahtjeve pomoću POST /v1/batches/{batch_id}/requests. Svaki poziv nosi popis zahtjeva, a krajnju točku možeš zvati koliko god puta trebaš sve dok batch nije otkazan. Ovaj pristup radi za batcheve koji se grade postupno.
Struktura zahtjeva
Tijelo poziva sadrži polje batch_requests. Svaki element uparuje identifikator (batch_request_id) sa samim zahtjevom, pohranjenim pod ključem koji odgovara njegovoj vrsti – responses za 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: Tvoj identifikator, jedinstven unutar batcha. To je ključ koji povezuje zahtjev s njegovim rezultatom; ako nedostaje, xAI generira UUID.batch_request: Zahtjev, pod ključem za njegovu vrstu; REST referenca također dokumentirachat_get_completionza format Chat Completions.
Za slike i videozapise upotrijebi SDK (lekcija 9) ili JSONL datoteku (sljedeća lekcija).
cURL zahtjev
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."}
]
}
}
}
]
}'
Dodavanje pomoću Python SDK-ja
Uz SDK, svaki zahtjev gradiš kao standardni razgovor, dodjeljuješ mu batch_request_id, a zatim ih dodaješ u grupama:
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)
# Dodaj u grupama od 100: jedan API poziv po grupi
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentacija ne postavlja maksimalan broj zahtjeva po pozivu; umjerene veličine grupa jednostavno ograničavaju ono što treba ponovno poslati u slučaju mrežnog incidenta.
Ograničenja brzine (Rate Limits) pri dodavanju
Tim može izvršiti do 1000 poziva za dodavanje svakih 30 sekundi, u kliznom prozoru koji se dijeli među svim njegovim batchevima. Ograničenje se odnosi na pozive, a ne na zahtjeve: s grupama od 100 zahtjeva, to već omogućuje više od 3000 zahtjeva u sekundi. Dva druga ograničenja su važnija:
- 25 MB maksimum po pojedinačnom zahtjevu, što se uglavnom tiče slika kodiranih u base64
- Iznad 100 000 zahtjeva u batchu, xAI može usporiti obradu kako bi očuvao stabilnost usluge
Kada koristiti dodavanje putem API-ja
Dodavanje putem API-ja radi kad god je fleksibilnost važnija od pripreme unaprijed. Postaje prirodan izbor kada se batch gradi postupno: zahtjevi koji stižu iz reda čekanja dodaju se kako pristižu, dok bi JSONL datoteka zahtijevala da unaprijed znaš sve – i zatvorila bi batch. To je također put za izradu prototipova, za testiranje cijelog tijeka rada s pet zahtjeva prije skaliranja, te za heterogene batcheve.
Validacija zahtjeva
Provjeri statusni kod svakog poziva za dodavanje: pogreška u ovoj fazi znači da grupa nije spremljena i moraš je ponovno poslati. Zahtjev također može kasnije ne uspjeti, tijekom obrade; tada se pojavljuje u rezultatima sa svojom porukom o pogrešci. Model koji ne prihvaća batch bit će odbijen s porukom not supported for batch processing: prije pokretanja velikog batcha provjeri podobnost na stranici modela.
Ključne točke
- Dodavanje ide kroz
POST /v1/batches/{id}/requests, s popisombatch_requests - Svaki zahtjev nosi jedinstveni
batch_request_idi svoj sadržaj pod ključem za svoju vrstu (responses,chat_get_completion) - SDK gradi zahtjeve s
client.chat.create(..., batch_request_id=...)i dodaje ih sclient.batch.add - Ograničenje je 1000 poziva za dodavanje svakih 30 sekundi za tim, a svaki poziv može nositi mnogo zahtjeva
- Za razliku od JSONL datoteke, dodavanje putem API-ja ostavlja batch otvorenim za nova dodavanja