Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Lihtne POST /v1/responses päring

Õppetund 9 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Sinu esimene edukas kutse
  2. Päringu struktuur
  3. Vastuse anatoomia
  4. Levinud valikulised parameetrid
  5. Vestluse jätkamine
  6. Kulude jälgimine
  7. Peamised punktid

Uuendatud 3. novembril 2026, lähtudes xAI parimatest tavadest ja API dokumentatsioonist: temperatuur on piiratud väärtusega 1 ning xAI soovitab kasutada 0.7 koos top_p väärtusega 0.95. Allikas: Parimad tavad.

Sinu esimene edukas kutse

Sul on konto olemas, API võti käes ja SDK paigaldatud. On aeg saata oma esimene päring Grok API-le ja mõista vastuse struktuuri. See tund keskendub peamisele lõpp-punktile /v1/responses, mis on kõige kaasaegsem ja enim soovitatud.

Päringu struktuur

Lõpp-punkt POST /v1/responses nõuab vähemalt kahte parameetrit:

  • model: kasutatava mudeli ID
  • input: sinu päringu tekst (või täpsematel juhtudel sisu massiiv)

Minimaalne päring Pythonis

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.5",
    input="What's the most widely used programming language in 2026?"
)

print(response.output[0].content[0].text)

Süsteemi juhistega

Parameeter instructions võimaldab määratleda mudeli käitumist:

response = client.responses.create(
    model="grok-4.5",
    instructions="You are a web development expert. Answer concisely.",
    input="What's the difference between SSR and SSG?"
)

Vastuse anatoomia

API tagastab struktureeritud JSON-objekti. Siin on peamised väljad:

{
  "id": "resp-abc123",
  "object": "response",
  "status": "completed",
  "model": "grok-4.5",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The model's answer appears here."
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156,
    "total_tokens": 198
  }
}

Olulised väljad

  • id: vastuse kordumatu ID, kasulik selle hilisemaks retrieve’rimiseks
  • status: completed, kui genereerimine on lõppenud
  • output: massiiv, mis sisaldab genereeritud sõnumeid
  • usage: tokenite loendurid sinu tarbimise jälgimiseks

Levinud valikulised parameetrid

Loomingulisuse juhtimine

response = client.responses.create(
    model="grok-4.5",
    input="Suggest a name for an AI startup.",
    temperature=0.7,  # xAI soovitatud väärtus
    top_p=0.95,
)
  • API aktsepteerib temperatuuri vahemikus 0 kuni 2, kuid piirab kõik suuremad väärtused 1-ga
  • xAI soovitab temperature=0.7 ja top_p=0.95 ning hoiatab nende muutmise eest: kvaliteet tavaliselt langeb
  • Suurema loomingulisuse saamiseks küsi seda otseselt vihjes („paku ootamatuid nimesid“)

Pikkuse piiramine

response = client.responses.create(
    model="grok-4.5",
    input="Summarize the concept of machine learning.",
    max_output_tokens=200  # Piirab vastust
)

Põhjendamise sisselülitamine

Põhjendamismudelite puhul saad kohandada mõtlemise intensiivsust:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this problem: if 3x + 7 = 22, what is x?",
    reasoning={"effort": "high"}
)

Võimalikud tasemed on low, medium ja high.

Vestluse jätkamine

Lõpp-punkt /v1/responses toetab mitmevoorulisi vestlusi parameetri previous_response_id kaudu:

# Esimene sõnum
r1 = client.responses.create(
    model="grok-4.5",
    input="I'm building an API in Python."
)

# Teine sõnum (mudel mäletab konteksti)
r2 = client.responses.create(
    model="grok-4.5",
    input="Which framework do you recommend?",
    previous_response_id=r1.id
)

See lähenemine on lihtsam kui sõnumite ajaloo ise haldamine.

Kulude jälgimine

Vastuses olev väli usage võimaldab arvutada iga kutse hinda. Väli output_tokens_details.reasoning_tokens näitab, mitu tokenit kulus mudeli sisemisele põhjendamisele (neid tokeneid arvestatakse tasu hulka, kuid need ei ilmu vastuses).

Peamised punktid

  • Lõpp-punkt POST /v1/responses on kõige kaasaegsem ja enim soovitatud
  • Kaks kohustuslikku parameetrit: model ja input
  • Vastus asub aadressil output[0].content[0].text
  • Kasuta previous_response_id mitmevooruliste vestluste jaoks
  • Väli usage aitab jälgida sinu tokenite tarbimist