Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Verzoeken in JSON toevoegen

Les 5 van 12 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Toevoegen via de API
  2. Structuur van het verzoek
  3. cURL-verzoek
  4. Toevoegen met de Python SDK
  5. Snelheidslimieten bij toevoegen
  6. Wanneer API-toevoeging gebruiken
  7. Validatie van verzoeken
  8. Belangrijkste punten

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 ook chat_get_completion voor 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 een batch_requests-lijst.
  • Elk verzoek bevat een unieke batch_request_id en 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 met client.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.