Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Yksinkertainen POST /v1/responses -pyyntö

Oppitunti 9 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ensimmäinen onnistunut kutsusi
  2. Pyynnön rakenne
  3. Vastauksen anatomia
  4. Yleisiä valinnaisia parametreja
  5. Keskustelun jatkaminen
  6. Kulujen seuranta
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n parhaiden käytäntöjen ja API-viitteen perusteella: lämpötila on rajoitettu arvoon 1, ja xAI suosittelee arvoa 0.7 yhdessä top_p:n arvon 0.95 kanssa. Lähde: Parhaat käytännöt.

Ensimmäinen onnistunut kutsusi

Sinulla on tili, API-avain ja asennettu SDK. On aika lähettää ensimmäinen pyyntösi Grok API:lle ja ymmärtää vastauksen rakenne. Tämä oppitunti keskittyy päätepisteeseen /v1/responses, joka on nykyaikaisin ja eniten suositeltu vaihtoehto.

Pyynnön rakenne

POST /v1/responses -päätepiste vaatii vähintään kaksi parametria:

  • model: käytettävän mallin tunnus
  • input: pyyntösi teksti (tai sisältötaulukko edistyneissä tapauksissa)

Minimipyyntö Pythonilla

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)

Järjestelmäohjeiden kanssa

instructions-parametrilla voit määrittää mallin toimintatavan:

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?"
)

Vastauksen anatomia

API palauttaa jäsennellyn JSON-objektin. Tässä ovat tärkeimmät kentät:

{
  "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
  }
}

Tärkeät kentät

  • id: vastauksen yksilöllinen tunnus, hyödyllinen myöhempää hakua varten
  • status: completed, kun generointi on valmis
  • output: taulukko, joka sisältää generoidut viestit
  • usage: token-laskurit kulutuksen seurantaan

Yleisiä valinnaisia parametreja

Luovuuden hallinta

response = client.responses.create(
    model="grok-4.5",
    input="Suggest a name for an AI startup.",
    temperature=0.7,  # xAI:n suosittelema arvo
    top_p=0.95,
)
  • API hyväksyy lämpötilan välillä 0–2, mutta rajoittaa kaikki tätä suuremmat arvot ykköseen
  • xAI suosittelee arvoja temperature=0.7 ja top_p=0.95 ja neuvoo poikkeamaan niistä: laatu heikkenee yleensä
  • Jos haluat enemmän luovuutta, pyydä sitä kehotteessa (“ehdota odottamattomia nimiä”)

Pituuden rajoittaminen

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

Päättelyn kytkeminen päälle

Säädä päättelymalleissa ajatteluponnistelua:

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

Mahdolliset tasot ovat low, medium ja high.

Keskustelun jatkaminen

/v1/responses-päätepiste tukee monivaiheisia keskusteluja previous_response_id-parametrin avulla:

# Ensimmäinen viesti
r1 = client.responses.create(
    model="grok-4.5",
    input="I'm building an API in Python."
)

# Toinen viesti (malli muistaa kontekstin)
r2 = client.responses.create(
    model="grok-4.5",
    input="Which framework do you recommend?",
    previous_response_id=r1.id
)

Tämä lähestymistapa on yksinkertaisempi kuin viestihistorian hallinta itse.

Kulujen seuranta

Vastauksen usage-kentän avulla voit laskea jokaisen kutsun kustannukset. Kenttä output_tokens_details.reasoning_tokens näyttää, kuinka monta tokenia kului mallin sisäiseen päättelyyn (näistä tokeneista veloitetaan, mutta niitä ei näy vastauksessa).

Keskeiset asiat

  • POST /v1/responses on nykyaikaisin ja eniten suositeltu päätepiste
  • Kaksi vaadittua parametria: model ja input
  • Vastaus löytyy kohdasta output[0].content[0].text
  • Käytä previous_response_id:tä monivaiheisiin keskusteluihin
  • usage-kenttä auttaa seuraamaan token-kulutustasi