Das Antwortformat verstehen
Auf dieser Seite
Anatomie einer Antwort
Wenn Sie eine Anfrage an POST /v1/responses senden, gibt der xAI-Server ein strukturiertes JSON-Objekt zurück. Das Verständnis jedes Feldes in diesem Objekt ist unerlässlich, um die Ergebnisse in Ihrer Anwendung korrekt zu verwenden.
Komplette Struktur
Hier ist eine typische Antwort:
{
"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
}
}
Hauptfelder
id
Die eindeutige Kennung für die Antwort im Format resp-xxx. Sie verwenden diese Kennung, um:
- Gespräche mit
previous_response_idzu verketten - Eine gespeicherte Antwort mit
GET /v1/responses/{id}abzurufen - Eine Antwort mit
DELETE /v1/responses/{id}zu löschen
status
Der Status der Antwort:
| Status | Bedeutung |
|---|---|
completed | Antwort wurde erfolgreich generiert |
failed | Fehler während der Generierung |
incomplete | Antwort wurde unterbrochen (Token-Limit, Inhaltsfilter) |
in_progress | Generierung läuft (Streaming) |
Überprüfen Sie den Status immer vor der Verwendung des Antwortinhalts in Ihrem Code.
output
Ein Array, das die Antwortelemente enthält. Jedes Element hat ein type:
message: Textantwort des Modellsfunction_call: Vom Modell angeforderte Tool-Aufrufe
Der Textinhalt befindet sich bei output[0].content[0].text. Annotationen (Zitate, Links) sind im annotations-Array desselben Objekts enthalten.
usage
Nutzungsdaten, im Folgenden detailliert beschrieben.
Das usage-Objekt verstehen
Das usage-Objekt ist entscheidend für die Kostenverfolgung:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Eingabe- und Ausgabetokens
input_tokens: Anzahl der Tokens in Ihrer Eingabeaufforderung (und in der Historie bei der Verkettung von Gesprächen)output_tokens: Gesamtzahl der generierten Tokens, inklusive der Rechen-Tokentotal_tokens: Summe beider Werte
Rechen-Token
output_tokens_details.reasoning_tokens gibt an, wie viele Tokens das Modell für seine interne Rechenleistung verwendet hat. Diese Tokens werden abgerechnet, sind aber nicht im Textantwort sichtbar.
Im obigen Beispiel sind von den 180 Ausgabetokens 120 für die Rechenleistung und nur 60 bilden die sichtbare Antwort. Dies ist ein typisches Verhältnis für Rechenmodelle.
Kosten in Nano-USD
cost_in_nano_usd gibt die exakten Kosten der Anfrage an. Die Umrechnung ist einfach:
Kosten in USD = cost_in_nano_usd / 1.000.000.000
Für unser Beispiel: 500000 / 1.000.000.000 = 0,0005 USD (0,0005 USD).
Serverseitige Tool-Nutzung
Wenn das Modell integrierte Tools verwendet, enthält das usage-Objekt zusätzlich:
{
"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
}
}
Dadurch erfahren Sie genau, welche Tools aufgerufen wurden und wie oft.
Text in Python extrahieren
Hier ist ein robustes Muster zum Extrahieren von Textinhalten:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Status prüfen
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Fehler: Status {response.status}")
# Nutzungsdaten anzeigen
print(f"Verwendete Tokens: {response.usage.total_tokens}")
print(f"Kosten: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Wichtige Erkenntnisse
- Jede Antwort verfügt über eine eindeutige
id, die für die Verkettung oder den Abruf wiederverwendet werden kann - Der
statusmuss immer vor der Verwendung des Inhalts überprüft werden - Der Text befindet sich bei
output[0].content[0].text reasoning_tokenswerden abgerechnet, sind aber in der Antwort unsichtbar- Die Division von
cost_in_nano_usddurch eine Milliarde ergibt die Kosten in Dollar