Verzoeken in JSON toevoegen
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 volgen de REST API en de officiële
xai-sdk(client.batch.*; de xAI Batch API gebruikt niet het OpenAI-formaat, 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 Reference · Batch Pricing.
Toevoegen via de API
Zodra de batch is aangemaakt, voegt u er verzoeken aan toe met POST /v1/batches/{batch_id}/requests. Elke oproep bevat een lijst met verzoeken. U kunt dit eindpunt zo vaak aanroepen als nodig is, zolang de batch niet is geannuleerd. Deze aanpak werkt voor batches die geleidelijk worden opgebouwd.
Structuur van het verzoek
De body van de oproep bevat een batch_requests-array. Elk element koppelt een identificatie (batch_request_id) aan het verzoek zelf, opgeslagen onder de sleutel die bij het type hoort—responses voor de 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: Uw eigen identificatie, uniek binnen de batch. Dit is de sleutel die het verzoek aan zijn resultaat koppelt; als deze ontbreekt, genereert xAI een UUID.batch_request: Het verzoek, onder de sleutel voor het betreffende type; de API-referentie documenteert ookchat_get_completionvoor het Chat Completions-formaat.
Gebruik voor afbeeldingen en video’s de SDK (les 9) of een JSONL-bestand (volgende les).
cURL-verzoek
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."}
]
}
}
}
]
}'
Toevoegen met de Python SDK
Met de SDK bouwt u elk verzoek op als een standaard conversatie, wijst u een batch_request_id toe en voegt u ze vervolgens in blokken toe:
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)
# In blokken van 100 toevoegen: één API-oproep per blok
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
De documentatie stelt geen maximumaantal verzoeken per oproep in; gematigde blokgroottes beperken eenvoudigweg wat opnieuw moet worden verzonden bij een netwerkincident.
Snelheidslimieten bij toevoegen
Een team kan maximaal 1.000 toevoeg-oproepen per 30 seconden uitvoeren, binnen een glijdend venster dat wordt gedeeld door al zijn batches. De limiet geldt voor oproepen, niet voor verzoeken: met blokken van 100 verzoeken zijn dit al meer dan 3.000 verzoeken per seconde. Twee andere grenzen zijn belangrijker:
- 25 MB maximum per individueel verzoek, wat voornamelijk van belang is voor afbeeldingen die in base64 zijn gecodeerd.
- Bij meer dan 100.000 verzoeken in een batch kan xAI de verwerking vertragen om de stabiliteit van de dienst te waarborgen.
Wanneer API-toevoeging gebruiken
API-toevoeging is geschikt wanneer flexibiliteit belangrijker is dan voorbereiding vooraf. Het wordt de natuurlijke keuze wanneer de batch geleidelijk wordt opgebouwd: verzoeken die uit een wachtrij binnenkomen, worden direct toegevoegd, terwijl een JSONL-bestand vereist dat alles vooraf bekend is—en de batch zou sluiten. Het is ook de route voor prototyping, om de volledige workflow met vijf verzoeken te testen voordat u opschalt, en voor heterogene batches.
Validatie van verzoeken
Controleer de statuscode van elke toevoeg-oproep: een fout in dit stadium betekent dat het blok niet is opgeslagen en dat u het opnieuw moet verzenden. Een verzoek kan ook later falen, tijdens de verwerking; het verschijnt dan in de resultaten met de bijbehorende foutmelding. Een model dat de batch niet accepteert, wordt geweigerd met het bericht not supported for batch processing: controleer de geschiktheid op de modelpagina voordat u een grote batch start.
Belangrijkste punten
- Toevoegen verloopt via
POST /v1/batches/{id}/requests, met eenbatch_requests-lijst. - Elk verzoek bevat een unieke
batch_request_iden de inhoud onder de sleutel voor het type (responses,chat_get_completion). - De SDK bouwt verzoeken op met
client.chat.create(..., batch_request_id=...)en voegt ze toe metclient.batch.add. - De limiet is 1.000 toevoeg-oproepen per 30 seconden voor het team; elke oproep kan veel verzoeken bevatten.
- In tegenstelling tot het JSONL-bestand, laat API-toevoeging de batch open staan voor nieuwe toevoegingen.