Suprasti atsako formatą
Šiame puslapyje
Atsako sandara
Kai siunti užklausą adresu POST /v1/responses, xAI serveris grąžina struktūrizuotą JSON objektą. Norint teisingai panaudoti rezultatus savo programoje, būtina suprasti kiekvieną šio objekto lauką.
Pilna struktūra
Štai tipiškas atsakas:
{
"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
}
}
Pagrindiniai laukai
id
Unikalus atsako identifikatorius formato resp-xxx. Jį naudosite:
- Pokalbių grandinėms kurti naudodami
previous_response_id - Įrašytam atsakui gauti su
GET /v1/responses/{id} - Atsakui ištrinti su
DELETE /v1/responses/{id}
status
Atsako būsena:
| Būsena | Reikšmė |
|---|---|
completed | Atsakas sėkmingai sugeneruotas |
failed | Įvyko klaida generavimo metu |
incomplete | Atsakas nutrauktas (tokenų limitas, turinio filtras) |
in_progress | Vyksta generavimas (srautinis režimas) |
Prieš naudodami atsako turinį savo kode, visada patikrinkite būseną.
output
Masyvas, kuriame yra atsako elementai. Kiekvienas elementas turi type:
message: Tekstinis modelio atsakasfunction_call: Modelio prašymas įvykdyti įrankį
Teksto turinys yra output[0].content[0].text. Anotacijos (citatos, nuorodos) yra to paties objekto annotations masyve.
usage
Naudojimo informacija, išsamiau aprašyta žemiau.
Suprasti usage objektą
usage objektas yra kritiškai svarbus stebint išlaidas:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Įvesties ir išvesties tokenai
input_tokens: Tokenų skaičius tavo užklausoje (ir istorijoje, jei jungiate pokalbius)output_tokens: Bendras sugeneruotų tokenų skaičius, įskaitant samprotavimustotal_tokens: Abiejų suma
Samprotavimų tokenai
output_tokens_details.reasoning_tokens nurodo, kiek tokenų modelis panaudojo vidiniams samprotavimams. Už šiuos tokenus mokama, tačiau jie nematomi teksto atsake.
Pirmiau pateiktame pavyzdyje iš 180 išvesties tokenų 120 skirta samprotavimams, o tik 60 sudaro matomą atsaką. Tai tipiškas samprotavimų modelių santykis.
Kaina nano-USD
cost_in_nano_usd nurodo tikslią užklausos kainą. Konvertuoti paprasta:
Kaina USD = cost_in_nano_usd / 1,000,000,000
Mūsų pavyzdžiui: 500000 / 1,000,000,000 = 0.0005 USD (0,0005 USD).
Įrankių naudojimas serverio pusėje
Kai modelis naudoja integruotus įrankius, usage objekte taip pat atsiranda:
{
"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
}
}
Tai leidžia tiksliai žinoti, kurie įrankiai buvo iškviesti ir kiek kartų.
Teksto ištraukimas naudojant Python
Štai patikimas šablonas teksto turiniui ištraukti:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Check status
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Display usage
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Svarbiausi punktai
- Kiekvienas atsakas turi unikalų
id, kurį galima pakartotinai naudoti grandinėms kurti arba duomenims gauti - Prieš naudodami turinį, visada patikrinkite
status - Tekstas yra
output[0].content[0].text - Už
reasoning_tokensmokama, tačiau atsake jų nematyti cost_in_nano_usdpadalijus iš milijardo gaunama kaina doleriais