Lisää pyyntöjä JSON-muodossa
Tällä sivulla
Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: eräalennus on 20 % kelvollisissa tekstimalleissa (ei 50 %), esimerkit noudattavat REST API:a ja virallista
xai-sdk:tä (client.batch.*; xAI:n erä-API ei käytä OpenAI-muotoa, joten OpenAI SDK ei sovellu), ja Responses API on ensisijainen Chat Completionsin edellä, joka on xAI:lla vanhentunut päätepiste. Lähteet: Batch API · REST Reference · Batch Pricing.
Lisääminen API:n kautta
Kun erä on luotu, lisäät siihen pyyntöjä osoitteeseen POST /v1/batches/{batch_id}/requests. Jokainen kutsu sisältää listan pyyntöjä, ja voit kutsua päätepistettä niin monta kertaa kuin tarvitaan, kunhan erää ei ole peruutettu. Tämä lähestymistapa toimii vähitellen rakennetuille erille.
Pyynnön rakenne
Kutsun runko sisältää batch_requests-taulukon. Jokainen alkio yhdistää tunnisteen (batch_request_id) itse pyyntöön, joka tallennetaan sen tyypin mukaiseen avaimeen – responses Responses API:ta varten:
{
"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: Oma tunnisteesi, joka on yksilöllinen erän sisällä. Tämä on avain, joka yhdistää pyynnön sen tulokseen; jos se puuttuu, xAI luo UUID:n.batch_request: Pyyntö sen tyypin mukaisessa avaimessa; API-viite dokumentoi myöschat_get_completion-avaimen Chat Completions -muotoa varten.
Käytä kuvia ja videoita varten SDK:ta (oppitunti 9) tai JSONL-tiedostoa (seuraava oppitunti).
cURL-pyyntö
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."}
]
}
}
}
]
}'
Lisääminen Python SDK:lla
SDK:n avulla jokainen pyyntö rakennetaan kuten tavallinen keskustelu, sille määritetään batch_request_id, ja sen jälkeen ne lisätään osissa:
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)
# Lisää 100 pyynnön erissä: yksi API-kutsu per erä
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentaatio ei määritä enimmäismäärää pyynnöille kutsua kohden; kohtuulliset eräkoot rajoittavat vain sitä määrää, joka joudutaan lähettämään uudelleen verkkohäiriön sattuessa.
Lisäämisen nopeusrajoitukset
Tiimi voi tehdä enintään 1 000 lisäyskutsua jokaista 30 sekuntia kohden liukuvassa ikkunassa, joka on yhteinen kaikille sen erille. Raja koskee kutsuja, ei pyyntöjä: 100 pyynnön erillä tämä mahdollistaa jo yli 3 000 pyyntöä sekunnissa. Kaksi muuta rajaa ovat tärkeämpiä:
- 25 Mt enimmäiskoko yksittäistä pyyntöä kohden, mikä koskee pääasiassa base64-koodattuja kuvia
- Yli 100 000 pyynnön jälkeen erässä xAI voi hidastaa käsittelyä palvelun vakauden säilyttämiseksi
Milloin käyttää API-lisäystä
API-lisäys toimii aina, kun joustavuus on tärkeämpää kuin etukäteisvalmistelu. Siitä tulee luonteva valinta, kun erä rakennetaan vähitellen: jonosta saapuvat pyynnöt lisätään sitä mukaa kun ne tulevat, kun taas JSONL-tiedosto vaatisi kaiken tiedon etukäteen – ja sulkisi erän. Se on myös reitti prototyyppaukseen, jotta voit testata koko työnkulun viidellä pyynnöllä ennen skaalaamista, sekä heterogeenisille erille.
Pyynnön validointi
Tarkista jokaisen lisäyskutsun tilakoodi: virhe tässä vaiheessa tarkoittaa, että erää ei tallennettu, ja sinun on lähetettävä se uudelleen. Pyyntö voi myös epäonnistua myöhemmin käsittelyn aikana; tällöin se näkyy tuloksissa virheilmoituksineen. Malli, joka ei hyväksy erää, hylätään viestillä not supported for batch processing: tarkista kelpoisuus mallisivulta ennen suuren erän käynnistämistä.
Keskeiset asiat
- Lisäys tapahtuu osoitteeseen
POST /v1/batches/{id}/requestskäyttäenbatch_requests-listaa - Jokainen pyyntö sisältää yksilöllisen
batch_request_id:n ja sen sisällön tyypin mukaisessa avaimessa (responses,chat_get_completion) - SDK rakentaa pyynnöt komennolla
client.chat.create(..., batch_request_id=...)ja lisää ne komennollaclient.batch.add - Raja on 1 000 lisäyskutsua 30 sekunnissa tiimiä kohden; jokainen kutsu voi sisältää useita pyyntöjä
- Toisin kuin JSONL-tiedosto, API-lisäys jättää erän auki uusille lisäyksille