Добавяне на заявки в JSON
На тази страница
Обновено на 2 ноември 2026 г. въз основа на документацията на xAI: отстъпката за пакетна обработка е 20% за подходящите текстови модели (не 50%), примерите следват REST API и официалния
xai-sdk(client.batch.*; Batch API на xAI не използва формата на OpenAI, SDK на OpenAI не се прилага), а Responses API има предимство пред Chat Completions, който е остаряла крайна точка в xAI. Източници: Batch API · REST Reference · Batch Pricing.
Добавяне чрез API
След като пакетът бъде създаден, добавяте заявки към него чрез POST /v1/batches/{batch_id}/requests. Всеки повикване носи списък със заявки и можете да извиквате крайната точка толкова пъти, колкото е необходимо, стига пакетът да не е отменен. Този подход работи за пакети, изградени постепенно.
Структура на заявката
Тялото на повикването съдържа масив batch_requests. Всеки елемент сдвоява идентификатор (batch_request_id) със самата заявка, съхранена под ключа за нейния тип – responses за 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: Вашият идентификатор, уникален в рамките на пакета. Това е ключът, който свързва заявката с нейния резултат; ако липсва, xAI генерира UUID.batch_request: Заявката, под ключа за нейния тип; справочникът на API документира същоchat_get_completionза формата на Chat Completions.
За изображения и видеоклипове използвайте SDK (урок 9) или JSONL файл (следващият урок).
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."}
]
}
}
}
]
}'
Добавяне с Python SDK
При използване на SDK всяка заявка се изгражда като стандартен разговор, присвоява ѝ се batch_request_id, след което ги добавяте на порции:
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)
# Добавяне на порции от 100: едно API повикване на порция
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Документацията не задава максимален брой заявки на повикване; умерените размери на порциите просто ограничават това, което трябва да бъде изпратено отново в случай на мрежов инцидент.
Ограничения на честотата при добавяне
Екипът може да прави до 1000 повиквания за добавяне на всеки 30 секунди в плъзгащ се прозорец, споделен между всички негови пакети. Ограничението важи за повикванията, а не за заявките: с порции от 100 заявки това вече позволява повече от 3000 заявки в секунда. Две други граници са по-важни:
- 25 MB максимум за отделна заявка, което засяга основно изображения, кодирани в base64.
- Над 100 000 заявки в пакет, xAI може да забави обработката, за да запази стабилността на услугата.
Кога да използвате добавяне чрез API
Добавянето чрез API работи винаги, когато гъвкавостта е по-важна от предварителната подготовка. То става естественият избор, когато пакетът се изгражда постепенно: заявките, пристигащи от опашка, се добавят веднага щом се появят, докато JSONL файлът би изисквал всичко да е известно предварително – и би затворил пакета. Това е също така пътят за прототипиране, за тестване на целия работен поток с пет заявки преди мащабиране, и за хетерогенни пакети.
Валидиране на заявките
Проверете кода на състоянието на всяко повикване за добавяне: грешка на този етап означава, че порцията не е запазена и трябва да я изпратите отново. Заявката може също да се провали по-късно, по време на обработката; тогава тя се появява в резултатите със своето съобщение за грешка. Модел, който не приема пакета, се отхвърля със съобщението not supported for batch processing: проверете допустимостта на страницата на модела преди стартиране на голям пакет.
Ключови изводи
- Добавянето става чрез
POST /v1/batches/{id}/requests, със списъкbatch_requests. - Всяка заявка носи уникален
batch_request_idи своето съдържание под ключа за нейния тип (responses,chat_get_completion). - SDK изгражда заявките с
client.chat.create(..., batch_request_id=...)и ги добавя сclient.batch.add. - Ограничението е 1000 повиквания за добавяне на 30 секунди за екипа, като всяко повикване може да носи много заявки.
- За разлика от JSONL файла, добавянето чрез API оставя пакета отворен за нови допълнения.