A válaszformátum megértése
Ezen az oldalon
Egy válasz felépítése
Amikor kérést küldesz a POST /v1/responses végpontra, az xAI szerver egy strukturált JSON objektumot ad vissza. Ezen objektum minden mezőjének megértése elengedhetetlen ahhoz, hogy alkalmazásodban helyesen tudd felhasználni az eredményeket.
Teljes struktúra
Íme egy tipikus válasz:
{
"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
}
}
Fő mezők
id
A válasz egyedi azonosítója resp-xxx formátumban. A következőkre használhatod:
- Beszélgetések láncolása a
previous_response_idsegítségével - Tárolt válasz lekérése a
GET /v1/responses/{id}végponttal - Válasz törlése a
DELETE /v1/responses/{id}végponttal
status
A válasz állapota:
| Állapot | Jelentés |
|---|---|
completed | A válasz sikeresen generálódott |
failed | Hiba történt a generálás során |
incomplete | A válasz megszakadt (tokenkorlát, tartalomszűrő) |
in_progress | Generálás folyamatban (streamelés) |
Mindig ellenőrizd az állapotot, mielőtt felhasználnád a válasz tartalmát a kódodban.
output
A válaszelemeket tartalmazó tömb. Minden elemnek van egy type mezője:
message: A modell szöveges válaszafunction_call: A modell által kért eszközlehívás (tool call)
A szöveges tartalom az output[0].content[0].text útvonalon található. Az annotációk (hivatkozások, linkek) ugyanennek az objektumnak az annotations tömbjében vannak.
usage
Használati információk, amelyeket alább részletezünk.
A usage objektum megértése
A usage objektum kulcsfontosságú a költségek nyomon követéséhez:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Bemeneti és kimeneti tokenek
input_tokens: A promptodban (és előzményekben, ha beszélgetést láncolsz) lévő tokenek számaoutput_tokens: A generált tokenek teljes száma, beleértve a következtetési (reasoning) tokeneket istotal_tokens: A kettő összege
Következtetési tokenek (Reasoning tokens)
Az output_tokens_details.reasoning_tokens megmutatja, hány tokent használt fel a modell a belső következtetéseire. Ezeket a tokeneket számlázzák, de nem láthatók a szöveges válaszban.
A fenti példában a 180 kimeneti tokenből 120 a következtetésre ment, és csak 60 alkotja a látható választ. Ez egy tipikus arány a következtető modelleknél.
Költség nano-USD-ben
A cost_in_nano_usd megadja a kérés pontos költségét. Az átváltás egyszerű:
Költség USD-ben = cost_in_nano_usd / 1 000 000 000
A példánkban: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 dollár).
Szerveroldali eszközhasználat
Amikor a modell beépített eszközöket használ, a usage objektum a következőket is tartalmazza:
{
"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
}
}
Ebből pontosan láthatod, mely eszközöket hívták meg és hányszor.
Szöveg kinyerése Pythonban
Íme egy megbízható minta a szöveges tartalom kinyerésére:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Állapot ellenőrzése
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Használat megjelenítése
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Főbb megállapítások
- Minden válasznak van egy egyedi
idazonosítója, amely újra felhasználható láncoláshoz vagy lekéréshez - Mindig ellenőrizd a
statusmezőt, mielőtt felhasználnád a tartalmat - A szöveg az
output[0].content[0].textútvonalon található - A
reasoning_tokensszámlázásra kerül, de nem látható a válaszban - A
cost_in_nano_usdértékét egymilliárddal elosztva megkapod a költséget dollárban