Radni tijek u četiri koraka
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za skupne zahtjeve iznosi 20 % na odgovarajuće tekstualne modele (ne 50 %); primjeri koriste REST API i službeni
xai-sdk(client.batch.*; Batch API xAI-ja ne slijedi format OpenAI-ja, stoga se SDK OpenAI-ja ne primjenjuje); a Responses API ima prednost nad Chat Completionsom, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST referenca · Cjenik za skupne zahtjeve.
Životni ciklus skupnog zahtjeva
Svaki skupni zahtjev prolazi kroz isti ciklus: stvaranje, dodavanje zahtjeva, obrada i dohvaćanje rezultata. Razumijevanje ovog ciklusa ključno je prije nego što prijeđeš na implementaciju jer svaki korak ima svoja ograničenja i najbolje prakse.
Korak 1: Stvaranje skupnog zahtjeva
Sve počinje pozivom POST /v1/batches s jednim obaveznim poljem: nazivom skupnog zahtjeva. API vraća jedinstveni identifikator (batch_id) koji koristiš za sve naknadne operacije.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Odgovor također sadrži datume stvaranja i isteka skupnog zahtjeva (create_time, expire_time) te objekt state čiji su brojači još uvijek na nuli.
Korak 2: Dodavanje zahtjeva
Postoje dvije metode:
Kroz API: zahtjeve šalješ pomoću POST /v1/batches/{batch_id}/requests. Svaki poziv nosi popis zahtjeva i možeš ih nastaviti dodavati sve dok skupni zahtjev nije otkazan. Ovo je put za skupne zahtjeve koji se grade postupno.
Kroz JSONL datoteku: pripremiš datoteku koja sadrži sve tvoje zahtjeve, učitaš je putem Files API-ja, a zatim stvoriš skupni zahtjev iz te datoteke. Skupni zahtjev tada postaje zapečaćen: daljnja dodavanja nisu moguća. Ovo je put za velike količine podataka pripremljene unaprijed.
Svaki zahtjev nosi jedinstveni identifikator unutar skupnog zahtjeva: batch_request_id u API-ju ili custom_id u JSONL datoteci. Ako ga izostaviš u API-ju, xAI generira UUID; umjesto toga navedi svoj vlastiti (npr. ID iz baze podataka): on služi kao ključ za povezivanje tvojih podataka i rezultata te jamči da se zahtjev obrađuje samo jednom.
Korak 3: Praćenje napretka
Obrada počinje čim stignu zahtjevi; ne postoji korak „pokretanja“. U međuvremenu, GET /v1/batches/{batch_id} vraća objekt state i njegove brojače: num_requests (ukupno), num_pending (na čekanju), num_success (uspješni), num_error (neuspjeli) i num_cancelled (otkazani).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Kada num_pending padne na nulu, svi su zahtjevi obrađeni, uspješno ili ne. Periodično ispitivanje (polling) je dovoljno: nekoliko sekundi za mali testni skupni zahtjev, nekoliko minuta za veliki.
Korak 4: Dohvaćanje rezultata
Rezultati se čitaju pomoću GET /v1/batches/{batch_id}/results, bez čekanja da skupni zahtjev završi: svaki je zahtjev dostupan čim bude obrađen. Odgovor je straniciiran: limit postavlja veličinu stranice (maksimalno 1000), a vraćeni pagination_token koristi se za zahtijevanje sljedeće stranice; na posljednjoj je stranici prazan.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Svaki rezultat nosi batch_request_id svog zahtjeva: to ti omogućuje rekonstrukciju mapiranja između tvojih ulaznih podataka i odgovora Groka.
Radni tijek u praksi
U produkcijskom cjevovodu radni se tijek obično prevodi u dva odvojena procesa:
- Proces slanja koji stvara skupni zahtjev, priprema i dodaje zahtjeve, a zatim pohranjuje
batch_id - Proces dohvaćanja koji periodički provjerava brojače i preuzima rezultate čim postanu dostupni
Ova odvojenost omogućuje ti integraciju Batch API-ja u arhitekture vođene događajima ili postojeće cjevovode podataka (cron zadaci, Apache Airflow, redovi čekanja).
Rukovanje greškama u radnom tijeku
Skupni zahtjev nema globalno stanje „uspješno“ ili „neuspješno“: čitaš ga kroz svoje brojače. Neuspjeli zahtjev povećava num_error i pojavljuje se u rezultatima sa svojom porukom o grešci, bez blokiranja ostalih. Stoga moraš ispitati svaki rezultat i rukovati neuspjesima slučaj po slučaj.
Dva događaja utječu na cijeli skupni zahtjev. Prvi je otkazivanje, od tvoje strane ili od strane xAI-ja, koji to zatim objašnjava u polju cancel_by_xai_message. To se događa posebno kada je redak u JSONL datoteci neispravan. Drugi je istek (expire_time), nakon kojeg rezultati više nisu dostupni: preuzmi ih pravodobno.
Ključne točke
- Radni tijek slijedi redoslijed: stvori (s nazivom), dodaj, prati, preuzmi
- Identifikator zahtjeva (
batch_request_idilicustom_idu JSONL-u) tvoj je ključ za povezivanje - Napredak se očituje iz brojača u
state; sve je obrađeno kada jenum_pendingjednak nuli - Rezultati su straniciirani (
limit,pagination_token) i dostupni čim budu obrađeni - Greške se rješavaju zahtjev po zahtjev; otkazivanje i istek utječu na cijeli skupni zahtjev