Adăugarea cererilor în format JSON
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%), exemplele urmează API-ul REST și SDK-ul oficial
xai-sdk(client.batch.*; API-ul Batch xAI nu folosește formatul OpenAI, iar SDK-ul OpenAI nu se aplică), iar API-ul Responses are prioritate față de Chat Completions, un punct final moștenit la xAI. Surse: Batch API · Referință REST · Prețuri Batch.
Adăugarea prin API
Odată creat lotul, adăugați cererile folosind POST /v1/batches/{batch_id}/requests. Fiecare apel conține o listă de cereri și puteți invoca punctul final de câte ori este necesar, atâta timp cât lotul nu este anulat. Această abordare funcționează pentru loturile construite incremental.
Structura cererii
Corpul apelului conține un tablou batch_requests. Fiecare element asociază un identificator (batch_request_id) cu cererea propriu-zisă, stocată sub cheia corespunzătoare tipului său – responses pentru API-ul Responses:
{
"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: Identificatorul dumneavoastră, unic în cadrul lotului. Aceasta este cheia care face legătura între cerere și rezultatul său; dacă lipsește, xAI generează un UUID.batch_request: Cererea, plasată sub cheia specifică tipului său; referința API documentează, de asemenea,chat_get_completionpentru formatul Chat Completions.
Pentru imagini și videoclipuri, utilizați SDK-ul (lecția 9) sau un fișier JSONL (lecția următoare).
Cerere cURL
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."}
]
}
}
}
]
}'
Adăugarea cu SDK-ul Python
Cu SDK-ul, fiecare cerere este construită ca o conversație standard, i se atribuie un batch_request_id, iar apoi le adăugați în blocuri:
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)
# Adăugare în blocuri de 100: un apel API per bloc
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Documentația nu stabilește un număr maxim de cereri per apel; dimensiuni moderate ale blocurilor limitează pur și simplu ceea ce trebuie retrimis în cazul unui incident de rețea.
Limite de rată la adăugare
O echipă poate efectua până la 1.000 de apeluri de adăugare la fiecare 30 de secunde, într-o fereastră glisantă partajată între toate loturile sale. Limita se aplică apelurilor, nu cererilor: cu blocuri de 100 de cereri, acest lucru permite deja mai mult de 3.000 de cereri pe secundă. Două alte limite sunt mai relevante:
- 25 MB maxim per cerere individuală, ceea ce privește în principal imaginile codificate în base64
- Peste 100.000 de cereri într-un lot, xAI poate încetini procesarea pentru a păstra stabilitatea serviciului
Când să utilizați adăugarea prin API
Adăugarea prin API funcționează ori de câte ori flexibilitatea contează mai mult decât pregătirea inițială. Devine alegerea naturală când lotul este construit incremental: cererile care sosesc dintr-o coadă sunt adăugate pe măsură ce apar, în timp ce un fișier JSONL ar necesita cunoașterea tuturor datelor în avans – și ar închide lotul. Este, de asemenea, calea pentru prototipare, pentru a testa fluxul complet de lucru cu cinci cereri înainte de a scala, și pentru loturile eterogene.
Validarea cererilor
Verificați codul de stare al fiecărui apel de adăugare: o eroare în această etapă înseamnă că blocul nu a fost salvat și trebuie să îl retrimiteți. O cerere poate eșua, de asemenea, mai târziu, în timpul procesării; în acest caz, aceasta apare în rezultate împreună cu mesajul de eroare. Un model care nu acceptă lotul este respins cu mesajul not supported for batch processing: verificați eligibilitatea pe pagina modelului înainte de a lansa un lot de mari dimensiuni.
Puncte cheie
- Adăugarea se face prin
POST /v1/batches/{id}/requests, cu o listăbatch_requests - Fiecare cerere conține un
batch_request_idunic și conținutul său sub cheia specifică tipului (responses,chat_get_completion) - SDK-ul construiește cererile cu
client.chat.create(..., batch_request_id=...)și le adaugă cuclient.batch.add - Limita este de 1.000 de apeluri de adăugare la 30 de secunde pentru echipă; fiecare apel poate transporta multe cereri
- Spre deosebire de fișierul JSONL, adăugarea prin API menține lotul deschis pentru noi adăugiri