Anfragen über JSON hinzufügen
Auf dieser Seite
Aktualisiert am 2. November 2026 basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle (nicht 50 %), die Beispiele folgen dem REST-API-Format und dem offiziellen
xai-sdk(client.batch.*; die xAI-Batch-API verwendet nicht das OpenAI-Format, das OpenAI-SDK ist nicht anwendbar), und die Responses API hat Vorrang vor Chat Completions, einem Legacy-Endpunkt bei xAI. Quellen: Batch API · REST Reference · Batch Pricing.
Hinzufügen über die API
Sobald der Batch erstellt wurde, fügen Sie Anfragen mit POST /v1/batches/{batch_id}/requests hinzu. Jeder Aufruf enthält eine Liste von Anfragen, und Sie können das Endpunkt so oft aufrufen, wie nötig, solange der Batch nicht storniert wurde. Dieser Ansatz funktioniert für Batches, die inkrementell aufgebaut werden.
Anforderungsstruktur
Der Aufruf-Body enthält ein batch_requests-Array. Jedes Element paart eine Identifizierung (batch_request_id) mit der eigentlichen Anfrage, die unter dem Schlüssel für ihren Typ gespeichert ist – responses für die Responses API:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Klassifizieren Sie die Stimmung: positiv, negativ oder neutral."},
{"role": "user", "content": "Das Produkt hat meine Erwartungen übertroffen!"}
]
}
}
}
]
}
batch_request_id: Ihre Identifizierung, eindeutig innerhalb des Batches. Dies ist der Schlüssel, der die Anfrage mit ihrem Ergebnis verknüpft; fehlt er, generiert xAI eine UUID.batch_request: Die Anfrage, unter dem Schlüssel für ihren Typ; die API-Referenz dokumentiert zudemchat_get_completionfür das Chat-Completions-Format.
Für Bilder und Videos verwenden Sie das SDK (Lektion 9) oder eine JSONL-Datei (nächste Lektion).
cURL-Anfrage
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": "Klassifizieren Sie diesen Text: positiv, neutral oder negativ."}
]
}
}
}
]
}'
Hinzufügen mit dem Python-SDK
Mit dem SDK wird jede Anfrage wie ein Standardgespräch aufgebaut und erhält eine batch_request_id; Sie fügen sie dann in Chunks hinzu:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "Erstes Dokument zur Analyse..."},
{"id": "doc-2", "text": "Zweites Dokument zur Analyse..."},
{"id": "doc-3", "text": "Drittes Dokument zur Analyse..."},
]
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("Fassen Sie das Dokument in zwei Sätzen zusammen."))
chat.append(user(doc["text"]))
requests.append(chat)
# In Chunks von 100 hinzufügen: ein API-Aufruf pro Chunk
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Die Dokumentation legt kein Maximum für die Anzahl der Anfragen pro Aufruf fest; moderate Chunk-Größen begrenzen lediglich, was im Falle eines Netzwerkausfalls erneut gesendet werden muss.
Ratenbegrenzungen beim Hinzufügen
Ein Team kann bis zu 1.000 Hinzufüge-Aufrufe alle 30 Sekunden vornehmen, in einem gleitenden Fenster, das für alle Batches des Teams gemeinsam genutzt wird. Die Begrenzung gilt für Aufrufe, nicht für Anfragen: Mit Chunks von 100 Anfragen sind damit bereits mehr als 3.000 Anfragen pro Sekunde möglich. Zwei weitere Grenzen sind wichtiger:
- 25 MB Maximum pro einzelner Anfrage, was sich hauptsächlich auf in Base64 codierte Bilder bezieht.
- Über 100.000 Anfragen in einem Batch hinaus kann xAI die Verarbeitung verlangsamen, um die Dienststabilität zu gewährleisten.
Wann API-Hinzufügen verwendet wird
API-Hinzufügen kommt zum Einsatz, wenn Flexibilität wichtiger ist als die vorabige Vorbereitung. Es wird zur natürlichen Wahl, wenn der Batch inkrementell aufgebaut wird: Anfragen, die aus einer Warteschlange eintreffen, werden hinzugefügt, sobald sie ankommen, wohingegen eine JSONL-Datei alles im Voraus kennen müsste und den Batch schließen würde. Es ist auch der Weg für Prototypen, um den gesamten Workflow mit fünf Anfragen zu testen, bevor hochskaliert wird, und für heterogene Batches.
Anforderungsvalidierung
Prüfen Sie den Statuscode jedes Hinzufüge-Aufrufs: Ein Fehler in dieser Phase bedeutet, dass das Chunk nicht gespeichert wurde, und Sie müssen es erneut senden. Eine Anfrage kann auch später, während der Verarbeitung, fehlschlagen; sie erscheint dann in den Ergebnissen mit ihrer Fehlermeldung. Ein Modell, das den Batch nicht akzeptiert, wird mit der Meldung not supported for batch processing abgelehnt: Prüfen Sie die Berechtigung auf der Modellseite, bevor Sie einen großen Batch starten.
Kernaussagen
- Hinzufügen erfolgt über
POST /v1/batches/{id}/requestsmit einerbatch_requests-Liste. - Jede Anfrage trägt eine eindeutige
batch_request_idund ihren Inhalt unter dem Schlüssel für ihren Typ (responses,chat_get_completion). - Das SDK baut Anfragen mit
client.chat.create(..., batch_request_id=...)auf und fügt sie mitclient.batch.addhinzu. - Die Grenze beträgt 1.000 Hinzufüge-Aufrufe pro 30 Sekunden für das Team; jeder Aufruf kann viele Anfragen enthalten.
- Im Gegensatz zur JSONL-Datei lässt API-Hinzufügen den Batch für neue Ergänzungen offen.