Werkstroom in vier stappen
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van de xAI-documentatie: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen (niet 50%); de voorbeelden gebruiken de REST API en de officiële
xai-sdk(client.batch.*; de Batch API van xAI volgt niet het formaat van OpenAI, dus de OpenAI SDK is niet van toepassing); en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST-referentie · Batch-prijzen.
De levenscyclus van een batch
Elke batch doorloopt dezelfde cyclus: aanmaken, verzoeken toevoegen, verwerken, resultaten ophalen. Het is essentieel deze cyclus te begrijpen voordat u overgaat tot implementatie, omdat elke stap zijn eigen beperkingen en beste praktijken heeft.
Stap 1: Een batch aanmaken
Alles begint met een POST /v1/batches-aanroep, met één verplicht veld: de naam van de batch. De API retourneert een unieke identificatie (batch_id) die u voor alle daaropvolgende bewerkingen gebruikt.
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"}'
Het antwoord bevat ook de aanmaak- en vervaldatum van de batch (create_time, expire_time) en een state-object waarvan de tellers allemaal nog op nul staan.
Stap 2: Verzoeken toevoegen
Er zijn twee methoden:
Via de API: u verzendt verzoeken met POST /v1/batches/{batch_id}/requests. Elke aanroep bevat een lijst met verzoeken en u kunt deze blijven toevoegen zolang de batch niet is geannuleerd. Dit is de route voor batches die geleidelijk worden opgebouwd.
Via een JSONL-bestand: u bereidt een bestand voor met al uw verzoeken, uploadt dit via de Files API en maakt vervolgens de batch aan op basis van dat bestand. De batch is dan afgesloten: toevoegingen zijn niet meer mogelijk. Dit is de route voor grote volumes die vooraf zijn voorbereid.
Elk verzoek heeft een unieke identificatie binnen de batch: batch_request_id in de API, custom_id in het JSONL-bestand. Als u dit in de API weglaat, genereert xAI een UUID; geef in plaats daarvan uw eigen identificatie op (bijvoorbeeld een database-ID): deze dient als koppelingssleutel tussen uw gegevens en de resultaten, en garandeert dat een verzoek slechts één keer wordt verwerkt.
Stap 3: Voortgang bewaken
De verwerking start zodra verzoeken binnenkomen; er is geen aparte “start”-stap. Ondertussen retourneert GET /v1/batches/{batch_id} het state-object en de bijbehorende tellers: num_requests (totaal), num_pending (in behandeling), num_success (geslaagd), num_error (mislukt) en num_cancelled (geannuleerd).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Wanneer num_pending op nul zakt, zijn alle verzoeken verwerkt, al dan niet succesvol. Periodiek peilen is voldoende: een paar seconden voor een kleine testbatch, een paar minuten voor een grote batch.
Stap 4: Resultaten ophalen
Resultaten worden gelezen met GET /v1/batches/{batch_id}/results, zonder te wachten tot de batch is voltooid: elk verzoek is beschikbaar zodra het is verwerkt. Het antwoord is gepagineerd: limit stelt de paginagrootte in (maximaal 1.000) en de geretourneerde pagination_token wordt gebruikt om de volgende pagina op te vragen; deze is leeg op de laatste pagina.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Elk resultaat bevat de batch_request_id van het bijbehorende verzoek: hiermee kunt u de koppeling tussen uw invoergegevens en de antwoorden van Grok reconstrueren.
De werkstroom in de praktijk
In een productieomgeving vertaalt de werkstroom zich doorgaans in twee afzonderlijke processen:
- Een indieningsproces dat de batch aanmaakt, verzoeken voorbereidt en toevoegt, en vervolgens de
batch_idopslaat - Een ophaalproces dat periodiek de tellers controleert en resultaten downloadt zodra deze beschikbaar komen
Deze scheiding stelt u in staat de Batch API te integreren in event-driven architecturen of bestaande datapipelines (cron-jobs, Apache Airflow, wachtrijen).
Foutafhandeling in de werkstroom
Een batch heeft geen globale status “geslaagd” of “mislukt”: u leest dit via de tellers. Een mislukt verzoek verhoogt num_error en verschijnt in de resultaten met de bijbehorende foutmelding, zonder de andere verzoeken te blokkeren. U moet daarom elk resultaat onderzoeken en storingen geval per geval afhandelen.
Twee gebeurtenissen beïnvloeden de volledige batch. De eerste is annulering, door u of door xAI, die dit vervolgens toelicht in het veld cancel_by_xai_message. Dit gebeurt bijvoorbeeld wanneer een regel in een JSONL-bestand ongeldig is. De andere is verloop (expire_time), waarna resultaten niet meer toegankelijk zijn: haal ze tijdig op.
Belangrijkste punten
- De werkstroom volgt de volgorde: aanmaken (met een naam), toevoegen, bewaken, ophalen
- De verzoek-identificatie (
batch_request_id, ofcustom_idin JSONL) is uw koppelingssleutel - De voortgang leest u uit de
state-tellers; alles is verwerkt wanneernum_pendingnul is - Resultaten zijn gepagineerd (
limit,pagination_token) en beschikbaar naarmate ze worden verwerkt - Fouten worden per verzoek afgehandeld; annulering en verloop beïnvloeden de volledige batch