Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Het antwoordformaat begrijpen

Les 4 van 16 Bijgewerkt op 30 juli 2026 Ontwikkelaar
Op deze pagina
  1. Anatomie van een antwoord
  2. Volledige structuur
  3. Belangrijkste velden
  4. Het usage-object begrijpen
  5. Server-side toolgebruik
  6. Tekst extraheren in Python
  7. Belangrijkste punten

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:

StatusBetekenis
completedAntwoord succesvol gegenereerd
failedFout tijdens generatie
incompleteAntwoord onderbroken (tokenlimiet, contentfilter)
in_progressGeneratie 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 model
  • function_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 redenering
  • total_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 id die hergebruikt kan worden voor koppeling of ophaling
  • Controleer altijd de status voordat u de inhoud gebruikt
  • De tekst bevindt zich op output[0].content[0].text
  • Voor reasoning_tokens wordt gefactureerd, maar ze zijn onzichtbaar in het antwoord
  • cost_in_nano_usd gedeeld door één miljard geeft de kosten in dollars