Pochopení formátu odpovědi
Na této stránce
Anatomie odpovědi
Když odešleš požadavek na POST /v1/responses, server xAI vrátí strukturovaný objekt JSON. Porozumění každému poli v tomto objektu je zásadní pro správné využití výsledků ve tvé aplikaci.
Kompletní struktura
Zde je typická odpověď:
{
"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í pole
id
Jedinečný identifikátor odpovědi ve formátu resp-xxx. Použiješ jej k:
- Řetězení konverzací pomocí
previous_response_id - Načtení uložené odpovědi pomocí
GET /v1/responses/{id} - Smazání odpovědi pomocí
DELETE /v1/responses/{id}
status
Stav odpovědi:
| Stav | Význam |
|---|---|
completed | Odpověď byla úspěšně vygenerována |
failed | Během generování došlo k chybě |
incomplete | Odpověď byla přerušena (limit tokenů, filtr obsahu) |
in_progress | Generování probíhá (streaming) |
Před použitím obsahu odpovědi ve svém kódu vždy zkontroluj stav.
output
Pole obsahující prvky odpovědi. Každý prvek má typ type:
message: Textová odpověď od modelufunction_call: Volání nástroje požadované modelem
Textový obsah se nachází na adrese output[0].content[0].text. Anotace (citace, odkazy) jsou v poli annotations stejného objektu.
usage
Informace o využití, podrobněji rozepsané níže.
Porozumění objektu usage
Objekt usage je klíčový pro sledování tvých nákladů:
{
"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 tokenů v tvém promptu (a v historii, pokud řetězíš konverzace)output_tokens: Celkový počet vygenerovaných tokenů, včetně uvažovánítotal_tokens: Součet obou hodnot
Tokeny uvažování
output_tokens_details.reasoning_tokens udává, kolik tokenů model použil pro své vnitřní uvažování. Tyto tokeny jsou zpoplatněny, ale v textové odpovědi nejsou viditelné.
V uvedeném příkladu je z 180 výstupních tokenů 120 určeno pro uvažování a pouze 60 tvoří viditelnou odpověď. To je pro modely zaměřené na uvažování typický poměr.
Náklady v nano-USD
cost_in_nano_usd udává přesné náklady na požadavek. Převod je jednoduchý:
Náklady v USD = cost_in_nano_usd / 1 000 000 000
Pro náš příklad: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 $).
Využití nástrojů na straně serveru
Když model použije vestavěné nástroje, objekt usage navíc obsahuje:
{
"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
}
}
Díky tomu přesně zjistíš, které nástroje byly vyvolány a kolikrát.
Extrakce textu v Pythonu
Zde je robustní vzor pro extrakci 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")
Klíčové poznatky
- Každá odpověď má jedinečné
id, které lze znovu použít pro řetězení nebo načtení - Před použitím obsahu vždy zkontroluj
status - Text se nachází na adrese
output[0].content[0].text reasoning_tokensjsou zpoplatněny, ale v odpovědi nejsou viditelné- Vydělením
cost_in_nano_usdjednou miliardou získáš náklady v dolarech