Pochopenie formátu odpovede
Na tejto strane
Anatómia odpovede
Keď odošleš požiadavku na POST /v1/responses, server xAI vráti štruktúrovaný objekt JSON. Pochopenie každého poľa v tomto objekte je nevyhnutné pre správne využitie výsledkov vo tvojej aplikácii.
Kompletná štruktúra
Tu je typická odpoveď:
{
"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
}
}
Hlavné polia
id
Jedinečný identifikátor odpovede vo formáte resp-xxx. Použiješ ho na:
- Reťazenie konverzácií pomocou
previous_response_id - Získanie uloženej odpovede cez
GET /v1/responses/{id} - Vymazanie odpovede cez
DELETE /v1/responses/{id}
status
Stav odpovede:
| Stav | Význam |
|---|---|
completed | Odpoveď bola úspešne vygenerovaná |
failed | Chyba počas generovania |
incomplete | Odpoveď bola prerušená (limit tokenov, filter obsahu) |
in_progress | Generovanie prebieha (streaming) |
Pred použitím obsahu odpovede vo svojom kóde vždy skontroluj stav.
output
Pole obsahujúce prvky odpovede. Každý prvok má typ type:
message: Textová odpoveď od modelufunction_call: Volanie nástroja požadované modelom
Textový obsah sa nachádza na adrese output[0].content[0].text. Anotácie (citácie, odkazy) sú v poli annotations toho istého objektu.
usage
Informácie o využití, podrobnejšie popísané nižšie.
Pochopenie objektu usage
Objekt usage je kľúčový pre sledovanie tvojich nákladov:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Vstupné a výstupné tokeny
input_tokens: Počet tokenov v tvojom promte (a v histórii, ak reťazíš konverzácie)output_tokens: Celkový počet vygenerovaných tokenov, vrátane uvažovaniatotal_tokens: Súčet oboch hodnôt
Tokeny uvažovania
output_tokens_details.reasoning_tokens udáva, koľko tokenov model použil na svoje vnútorné uvažovanie. Tieto tokeny sa účtujú, ale nie sú viditeľné v textovej odpovedi.
V uvedenom príklade z 180 výstupných tokenov pripadá 120 na uvažovanie a iba 60 tvorí viditeľnú odpoveď. Ide o typický pomer pre modely založené na uvažovaní.
Náklady v nano-USD
cost_in_nano_usd poskytuje presnú cenu požiadavky. Prevod je jednoduchý:
Náklady v USD = cost_in_nano_usd / 1 000 000 000
Pre náš príklad: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 $).
Využitie nástrojov na strane servera
Keď model použije vstavané nástroje, objekt usage obsahuje aj:
{
"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
}
}
To ti umožní presne zistiť, ktoré nástroje boli vyvolané a koľkokrát.
Extrakcia textu v Pythone
Tu je robustný vzor na extrakciu textového obsahu:
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")
Kľúčové poznatky
- Každá odpoveď má jedinečné
id, ktoré môžeš znovu použiť na reťazenie alebo získanie - Pred použitím obsahu vždy skontroluj
status - Text sa nachádza na adrese
output[0].content[0].text reasoning_tokenssa účtujú, ale v odpovedi nie sú viditeľnécost_in_nano_usdvydelené miliardou dáva náklady v dolároch