Forstå svarformatet
På denne side
Opbygningen af et svar
Når du sender en anmodning til POST /v1/responses, returnerer xAI-serveren et struktureret JSON-objekt. Det er afgørende, at du forstår hvert felt i dette objekt for korrekt at kunne bruge resultaterne i din applikation.
Komplet struktur
Her er et typisk svar:
{
"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
}
}
Hovedfelter
id
Den unikke identifikator for svaret i formatet resp-xxx. Du bruger den til at:
- Kæde samtaler sammen med
previous_response_id - Hente et gemt svar med
GET /v1/responses/{id} - Slette et svar med
DELETE /v1/responses/{id}
status
Svarets status:
| Status | Betydning |
|---|---|
completed | Svar genereret succesfuldt |
failed | Fejl under generering |
incomplete | Svar afbrudt (token-grænse, indholdsfilter) |
in_progress | Generering i gang (streaming) |
Tjek altid status, før du bruger svarindholdet i din kode.
output
Et array, der indeholder svarelementerne. Hvert element har en type:
message: Tekstsvar fra modellenfunction_call: Værktøjskald anmodet af modellen
Tekstindholdet findes på output[0].content[0].text. Annotationer (citationer, links) ligger i annotations-arrayet i samme objekt.
usage
Brugsinformation, som vi dykker ned i nedenfor.
Forstå usage-objektet
usage-objektet er afgørende for at spore dine omkostninger:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Input- og output-tokens
input_tokens: Antal tokens i din prompt (og i historikken, hvis du kæder samtaler sammen)output_tokens: Samlet antal genererede tokens, inklusive ræsonnementtotal_tokens: Summen af begge
Ræsonnementstokens
output_tokens_details.reasoning_tokens angiver, hvor mange tokens modellen brugte til sit interne ræsonnement. Disse tokens faktureres, men de er ikke synlige i tekstsvar.
I eksemplet ovenfor er 120 ud af 180 output-tokens brugt til ræsonnement, og kun 60 udgør det synlige svar. Dette er et typisk forhold for ræsonnementsmodeller.
Omkostninger i nano-USD
cost_in_nano_usd angiver den nøjagtige omkostning for anmodningen. Konverteringen er enkel:
Omkostning i USD = cost_in_nano_usd / 1.000.000.000
For vores eksempel: 500000 / 1.000.000.000 = 0,0005 USD (0,0005 $).
Brug af værktøjer på serversiden
Når modellen bruger indbyggede værktøjer, inkluderer usage-objektet også:
{
"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
}
}
Dette giver dig mulighed for præcist at se, hvilke værktøjer der blev kaldt, og hvor mange gange.
Uddrag af tekst i Python
Her er et robust mønster til at uddrage tekstindhold:
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")
Vigtige pointer
- Hvert svar har en unik
id, som kan genbruges til kædning eller hentning - Tjek altid
status, før du bruger indholdet - Teksten findes på
output[0].content[0].text reasoning_tokensfaktureres, men er usynlige i svaretcost_in_nano_usddivideret med én milliard giver omkostningen i dollars