Razumevanje formata odgovora
Na tej strani
Anatomija odgovora
Ko pošlješ zahtevo na POST /v1/responses, strežnik xAI vrne strukturiran objekt JSON. Razumevanje vsakega polja v tem objektu je ključno za pravilno uporabo rezultatov v tvoji aplikaciji.
Celotna struktura
Tukaj je tipičen odgovor:
{
"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
}
}
Glavna polja
id
Edinstveni identifikator odgovora v formatu resp-xxx. Uporabil ga boš za:
- Povezovanje pogovorov s
previous_response_id - Pridobivanje shranjenega odgovora z
GET /v1/responses/{id} - Brisanje odgovora z
DELETE /v1/responses/{id}
status
Stanje odgovora:
| Stanje | Pomen |
|---|---|
completed | Odgovor je bil uspešno ustvarjen |
failed | Napaka med ustvarjanjem |
incomplete | Odgovor prekinjen (omejitev žetonov, filter vsebine) |
in_progress | Ustvarjanje v teku (pretakanje) |
Pred uporabo vsebine odgovora v svoji kodi vedno preveri stanje.
output
Polje, ki vsebuje elemente odgovora. Vsak element ima type:
message: Besedilni odgovor modelafunction_call: Klic orodja, ki ga zahteva model
Besedilna vsebina se nahaja na output[0].content[0].text. Opombe (citat, povezave) so v polju annotations istega objekta.
usage
Informacije o porabi, podrobneje opisane spodaj.
Razumevanje objekta usage
Objekt usage je ključen za sledenje tvojim stroškom:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Vhodni in izhodni žetoni
input_tokens: Število žetonov v tvojem pozivu (in v zgodovini, če povezuješ pogovore)output_tokens: Skupno število ustvarjenih žetonov, vključno z razmišljanjemtotal_tokens: Vsota obeh
Žetoni za razmišljanje
output_tokens_details.reasoning_tokens kaže, koliko žetonov je model porabil za svoje notranje razmišljanje. Ti žetoni se zaračunajo, vendar niso vidni v besedilnem odgovoru.
V zgornjem primeru je od 180 izhodnih žetonov 120 namenjenih razmišljanju, le 60 pa sestavlja vidni odgovor. To je tipično razmerje za modele za razmišljanje.
Strošek v nano-USD
cost_in_nano_usd podaja točen strošek zahteve. Pretvorba je preprosta:
Strošek v USD = cost_in_nano_usd / 1.000.000.000
Za naš primer: 500000 / 1.000.000.000 = 0,0005 USD (0,0005 $).
Uporaba orodij na strani strežnika
Ko model uporabi vgrajena orodja, objekt usage vključuje tudi:
{
"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 omogoča, da točno veš, katera orodja so bila priklicana in kolikokrat.
Izločanje besedila v Pythonu
Tukaj je robusten vzorec za izločanje besedilne vsebine:
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")
Ključne ugotovitve
- Vsak odgovor ima edinstven
id, ki ga lahko ponovno uporabiš za povezovanje ali pridobivanje - Pred uporabo vsebine vedno preveri
status - Besedilo se nahaja na
output[0].content[0].text reasoning_tokensse zaračunajo, vendar v odgovoru niso vidnicost_in_nano_usd, deljen z milijardo, da strošek v dolarjih