Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Dodavanje zahtjeva u JSON-u

Lekcija 5 od 12 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Dodavanje putem API-ja
  2. Struktura zahtjeva
  3. cURL zahtjev
  4. Dodavanje pomoću Python SDK-ja
  5. Ograničenja brzine (Rate Limits) pri dodavanju
  6. Kada koristiti dodavanje putem API-ja
  7. Validacija zahtjeva
  8. Ključne točke

Ažurirano 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za batch iznosi 20 % na kvalificirane tekstualne modele (ne 50 %), primjeri slijede REST API i službeni xai-sdk (client.batch.*; xAI Batch API ne koristi OpenAI format, OpenAI SDK se ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST referenca · Cjenik za Batch.

Dodavanje putem API-ja

Nakon što stvoriš batch, dodaješ mu zahtjeve pomoću POST /v1/batches/{batch_id}/requests. Svaki poziv nosi popis zahtjeva, a krajnju točku možeš zvati koliko god puta trebaš sve dok batch nije otkazan. Ovaj pristup radi za batcheve koji se grade postupno.

Struktura zahtjeva

Tijelo poziva sadrži polje batch_requests. Svaki element uparuje identifikator (batch_request_id) sa samim zahtjevom, pohranjenim pod ključem koji odgovara njegovoj vrsti – responses za 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: Tvoj identifikator, jedinstven unutar batcha. To je ključ koji povezuje zahtjev s njegovim rezultatom; ako nedostaje, xAI generira UUID.
  • batch_request: Zahtjev, pod ključem za njegovu vrstu; REST referenca također dokumentira chat_get_completion za format Chat Completions.

Za slike i videozapise upotrijebi SDK (lekcija 9) ili JSONL datoteku (sljedeća lekcija).

cURL zahtjev

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."}
            ]
          }
        }
      }
    ]
  }'

Dodavanje pomoću Python SDK-ja

Uz SDK, svaki zahtjev gradiš kao standardni razgovor, dodjeljuješ mu batch_request_id, a zatim ih dodaješ u grupama:

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)

# Dodaj u grupama od 100: jedan API poziv po grupi
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Dokumentacija ne postavlja maksimalan broj zahtjeva po pozivu; umjerene veličine grupa jednostavno ograničavaju ono što treba ponovno poslati u slučaju mrežnog incidenta.

Ograničenja brzine (Rate Limits) pri dodavanju

Tim može izvršiti do 1000 poziva za dodavanje svakih 30 sekundi, u kliznom prozoru koji se dijeli među svim njegovim batchevima. Ograničenje se odnosi na pozive, a ne na zahtjeve: s grupama od 100 zahtjeva, to već omogućuje više od 3000 zahtjeva u sekundi. Dva druga ograničenja su važnija:

  • 25 MB maksimum po pojedinačnom zahtjevu, što se uglavnom tiče slika kodiranih u base64
  • Iznad 100 000 zahtjeva u batchu, xAI može usporiti obradu kako bi očuvao stabilnost usluge

Kada koristiti dodavanje putem API-ja

Dodavanje putem API-ja radi kad god je fleksibilnost važnija od pripreme unaprijed. Postaje prirodan izbor kada se batch gradi postupno: zahtjevi koji stižu iz reda čekanja dodaju se kako pristižu, dok bi JSONL datoteka zahtijevala da unaprijed znaš sve – i zatvorila bi batch. To je također put za izradu prototipova, za testiranje cijelog tijeka rada s pet zahtjeva prije skaliranja, te za heterogene batcheve.

Validacija zahtjeva

Provjeri statusni kod svakog poziva za dodavanje: pogreška u ovoj fazi znači da grupa nije spremljena i moraš je ponovno poslati. Zahtjev također može kasnije ne uspjeti, tijekom obrade; tada se pojavljuje u rezultatima sa svojom porukom o pogrešci. Model koji ne prihvaća batch bit će odbijen s porukom not supported for batch processing: prije pokretanja velikog batcha provjeri podobnost na stranici modela.

Ključne točke

  • Dodavanje ide kroz POST /v1/batches/{id}/requests, s popisom batch_requests
  • Svaki zahtjev nosi jedinstveni batch_request_id i svoj sadržaj pod ključem za svoju vrstu (responses, chat_get_completion)
  • SDK gradi zahtjeve s client.chat.create(..., batch_request_id=...) i dodaje ih s client.batch.add
  • Ograničenje je 1000 poziva za dodavanje svakih 30 sekundi za tim, a svaki poziv može nositi mnogo zahtjeva
  • Za razliku od JSONL datoteke, dodavanje putem API-ja ostavlja batch otvorenim za nova dodavanja