Het antwoordformaat begrijpen
Op deze pagina
Anatomie van een antwoord
Wanneer u een verzoek stuurt naar POST /v1/responses, retourneert de xAI-server een gestructureerd JSON-object. Het begrijpen van elk veld in dit object is essentieel om de resultaten correct in uw applicatie te gebruiken.
Volledige structuur
Hier is een typisch antwoord:
{
"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
}
}
Belangrijkste velden
id
De unieke identificatiecode voor het antwoord, in het formaat resp-xxx. U gebruikt deze om:
- Gesprekken te koppelen met
previous_response_id - Een opgeslagen antwoord op te halen met
GET /v1/responses/{id} - Een antwoord te verwijderen met
DELETE /v1/responses/{id}
status
De status van het antwoord:
| Status | Betekenis |
|---|---|
completed | Antwoord succesvol gegenereerd |
failed | Fout tijdens generatie |
incomplete | Antwoord onderbroken (tokenlimiet, contentfilter) |
in_progress | Generatie bezig (streaming) |
Controleer altijd de status voordat u de inhoud van het antwoord in uw code gebruikt.
output
Een array met de elementen van het antwoord. Elk element heeft een type:
message: Tekstantwoord van het modelfunction_call: Tool-aanroep gevraagd door het model
De tekstinhoud bevindt zich op output[0].content[0].text. Annotaties (citaten, links) staan in de annotations-array van hetzelfde object.
usage
Gebruiksinformatie, hieronder in detail uitgelegd.
Het usage-object begrijpen
Het usage-object is cruciaal voor het volgen van uw kosten:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Input- en outputtokens
input_tokens: Aantal tokens in uw prompt (en in de geschiedenis bij het koppelen van gesprekken)output_tokens: Totaal aantal gegenereerde tokens, inclusief redeneringtotal_tokens: Som van beide
Redeneringstokens
output_tokens_details.reasoning_tokens geeft aan hoeveel tokens het model heeft gebruikt voor zijn interne redenering. Voor deze tokens wordt gefactureerd, maar ze zijn niet zichtbaar in het tekstantwoord.
In het bovenstaande voorbeeld zijn van de 180 outputtokens er 120 bestemd voor redenering en vormen slechts 60 tokens het zichtbare antwoord. Dit is een typische verhouding voor redeneermodellen.
Kosten in nano-USD
cost_in_nano_usd geeft de exacte kosten van het verzoek. De omrekening is eenvoudig:
Kosten in USD = cost_in_nano_usd / 1.000.000.000
Voor ons voorbeeld: 500000 / 1.000.000.000 = 0,0005 USD ($0,0005).
Server-side toolgebruik
Wanneer het model ingebouwde tools gebruikt, bevat het usage-object ook:
{
"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
}
}
Hiermee weet u precies welke tools zijn aangeroepen en hoe vaak.
Tekst extraheren in Python
Hier is een robuust patroon om tekstinhoud te extraheren:
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")
Belangrijkste punten
- Elk antwoord heeft een unieke
iddie hergebruikt kan worden voor koppeling of ophaling - Controleer altijd de
statusvoordat u de inhoud gebruikt - De tekst bevindt zich op
output[0].content[0].text - Voor
reasoning_tokenswordt gefactureerd, maar ze zijn onzichtbaar in het antwoord cost_in_nano_usdgedeeld door één miljard geeft de kosten in dollars