Ymmärrä vastausmuoto
Tällä sivulla
Vastauksen anatomia
Kun lähetät pyynnön osoitteeseen POST /v1/responses, xAI-palvelin palauttaa jäsennellyn JSON-objektin. Jokaisen tässä objektissa olevan kentän ymmärtäminen on välttämätöntä, jotta voit hyödyntää tuloksia oikein sovelluksessasi.
Täydellinen rakenne
Tässä on tyypillinen vastaus:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Tärkeimmät kentät
id
Vastauksen yksilöllinen tunniste muodossa resp-xxx. Käytät sitä seuraaviin tarkoituksiin:
- Keskustelujen ketjuttamiseen parametrilla
previous_response_id - Tallennetun vastauksen noutamiseen komennolla
GET /v1/responses/{id} - Vastauksen poistamiseen komennolla
DELETE /v1/responses/{id}
status
Vastauksen tila:
| Tila | Merkitys |
|---|---|
completed | Vastaus luotu onnistuneesti |
failed | Virhe luonnin aikana |
incomplete | Vastaus keskeytetty (tokinirajoitus, sisältösuodatin) |
in_progress | Luonti käynnissä (streaming) |
Tarkista aina tila ennen vastauksen sisällön käyttämistä koodissasi.
output
Taulukko, joka sisältää vastauselementit. Jokaisella elementillä on type:
message: Mallin tuottama tekstivastausfunction_call: Mallin pyytämä työkalukutsu
Tekstisisältö sijaitsee osoitteessa output[0].content[0].text. Annotaatiot (lähdeviitteet, linkit) löytyvät saman objektin annotations-taulukosta.
usage
Käyttötiedot, jotka on eritelty alla.
Ymmärrä usage-objekti
usage-objekti on ratkaisevan tärkeä kustannusten seurannassa:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Syöte- ja tulostetokit
input_tokens: Kehotteesi (prompt) tokien määrä (sekä historia, jos ketjutat keskusteluja)output_tokens: Luotujen tokien kokonaismäärä, päättely mukaan lukientotal_tokens: Molempien summa
Päättelytokit
output_tokens_details.reasoning_tokens kertoo, kuinka monta tokia malli käytti sisäiseen päättelyynsä. Näistä tokeista veloitetaan, mutta niitä ei näy tekstivastauksessa.
Yllä olevassa esimerkissä 180 tulostetokista 120 on varattu päättelyyn ja vain 60 muodostaa näkyvän vastauksen. Tämä on tyypillinen suhde päättelymalleille.
Kustannus nano-USD-muodossa
cost_in_nano_usd ilmoittaa pyynnön tarkan hinnan. Muunnos on yksinkertainen:
Kustannus USD = cost_in_nano_usd / 1 000 000 000
Esimerkissämme: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 dollaria).
Palvelinpuolen työkalujen käyttö
Kun malli käyttää sisäänrakennettuja työkaluja, usage-objekti sisältää myös seuraavat tiedot:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
Tämän avulla näet tarkasti, mitä työkaluja on kutsuttu ja kuinka monta kertaa.
Tekstin erottaminen Pythonilla
Tässä on vahva malli tekstisisällön erottamiseen:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Tarkista tila
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Näytä käyttö
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Keskeiset asiat
- Jokaisella vastauksella on yksilöllinen
id, jota voi käyttää ketjutukseen tai noutoon - Tarkista aina
statusennen sisällön käyttämistä - Teksti sijaitsee osoitteessa
output[0].content[0].text reasoning_tokensveloitetaan, mutta niitä ei näy vastauksessacost_in_nano_usdjaettuna miljardilla antaa kustannuksen dollareina