Tilføj anmodninger i JSON
På denne side
Opdateret 2. november 2026 baseret på xAI-dokumentation: batch-rabatten er 20 % på berettigede tekstmodeller (ikke 50 %), eksemplerne følger REST API’en og det officielle
xai-sdk(client.batch.*; xAI Batch API bruger ikke OpenAI-formatet, og OpenAI SDK gælder ikke), og Responses API har forrang frem for Chat Completions, som er et forældet endpoint hos xAI. Kilder: Batch API · REST-reference · Batch-prissætning.
Tilføjelse via API’en
Når batchen er oprettet, tilføjer du anmodninger til den med POST /v1/batches/{batch_id}/requests. Hvert kald indeholder en liste over anmodninger, og du kan kalde endpointet så mange gange, som det er nødvendigt, så længe batchen ikke er annulleret. Denne fremgangsmåde fungerer for batcher, der bygges inkrementelt.
Anmodningsstruktur
Kaldets body indeholder et batch_requests-array. Hvert element parer en identifikator (batch_request_id) med selve anmodningen, gemt under nøglen for dens type – responses til 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: Din identifikator, unik inden for batchen. Dette er nøglen, der matcher anmodningen med dens resultat; hvis den mangler, genererer xAI en UUID.batch_request: Anmodningen under nøglen for dens type; API-referencen dokumenterer ogsåchat_get_completiontil Chat Completions-formatet.
Brug SDK’en (lektion 9) eller en JSONL-fil (næste lektion) til billeder og videoer.
cURL-anmodning
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."}
]
}
}
}
]
}'
Tilføjelse med Python SDK
Med SDK’en bygges hver anmodning som en standard samtale, tildeles en batch_request_id, og derefter tilføjer du dem i bidder:
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)
# Tilføj i bidder på 100: ét API-kald pr. bid
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentationen angiver ikke et maksimum antal anmodninger pr. kald; moderate bidstørrelser begrænser blot mængden, der skal sendes igen i tilfælde af netværksproblemer.
Rategrænser for tilføjelse
Et team kan foretage op til 1.000 tilføjelseskald hvert 30. sekund i et glidende vindue, der deles på tværs af alle dets batcher. Grænsen gælder for kald, ikke anmodninger: med bidder på 100 anmodninger muliggør dette allerede mere end 3.000 anmodninger i sekundet. To andre grænser er vigtigere:
- 25 MB maksimum pr. individuel anmodning, hvilket primært vedrører billeder kodet i base64.
- Ved over 100.000 anmodninger i en batch kan xAI nedsætte behandlingshastigheden for at bevare tjenestens stabilitet.
Hvornår skal du bruge API-tilføjelse?
API-tilføjelse fungerer, når fleksibilitet vejer tungere end forberedelse på forhånd. Det bliver det naturlige valg, når batchen bygges inkrementelt: anmodninger, der ankommer fra en kø, tilføjes, efterhånden som de kommer ind, hvorimod en JSONL-fil ville kræve, at alt var kendt på forhånd – og ville lukke batchen. Det er også vejen til prototyping for at teste hele workflowet med fem anmodninger, før du skalerer op, og til heterogene batcher.
Validering af anmodninger
Tjek statuskoden for hvert tilføjelseskald: en fejl på dette tidspunkt betyder, at bidden ikke blev gemt, og du skal sende den igen. En anmodning kan også fejle senere under behandlingen; den vises derefter i resultaterne med sin fejlmeddelelse. En model, der ikke accepterer batchen, afvises med meddelelsen not supported for batch processing: tjek berettigelsen på modelsiden, før du lancerer en stor batch.
Vigtige pointer
- Tilføjelse sker via
POST /v1/batches/{id}/requestsmed enbatch_requests-liste. - Hver anmodning bærer en unik
batch_request_idog sit indhold under nøglen for dens type (responses,chat_get_completion). - SDK’en bygger anmodninger med
client.chat.create(..., batch_request_id=...)og tilføjer dem medclient.batch.add. - Grænsen er 1.000 tilføjelseskald pr. 30 sekunder for teamet; hvert kald kan indeholde mange anmodninger.
- I modsætning til JSONL-filen lader API-tilføjelse batchen stå åben for nye tilføjelser.