Fhem il-format tar-rispons
F'din il-paġna
Anatomija ta’ rispons
Meta tibgħat talba lil POST /v1/responses, is-server ta’ xAI jirritorna oġġett JSON strutturat. Li tifhem kull qasam f’dan l-oġġett huwa essenzjali biex tuża r-riżultati b’mod korrett fl-applikazzjoni tiegħek.
Struttura sħiħa
Hawnhekk hawn eżempju ta’ rispons tipiku:
{
"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
}
}
Oqsma ewlenin
id
L-identifikatur uniku għar-rispons, fil-format resp-xxx. Se tużah biex:
- Tgħaqqad konversazzjonijiet b’
previous_response_id - Tirrikupra rispons maħżun b’
GET /v1/responses/{id} - Tħassar rispons b’
DELETE /v1/responses/{id}
status
L-istatus tar-rispons:
| Status | Tifsira |
|---|---|
completed | Ir-rispons ġie ġġenerat b’suċċess |
failed | Żball waqt il-ġenerazzjoni |
incomplete | Ir-rispons ġie interrott (limitu ta’ tokens, filtru tal-kontenut) |
in_progress | Ġenerazzjoni għaddejja (streaming) |
Dejjem iċċekkja l-istatus qabel ma tuża l-kontenut tar-rispons fil-kodiċi tiegħek.
output
Array li fih l-elementi tar-rispons. Kull element għandu type:
message: Rispons testwali mill-mudellfunction_call: Sejħa ta’ għodda mitluba mill-mudell
Il-kontenut testwali jinsab f’output[0].content[0].text. L-annotazzjonijiet (ċitazzjonijiet, links) jinsabu fl-array annotations tal-istess oġġett.
usage
Informazzjoni dwar l-użu, iddettaljata hawn taħt.
Fhem l-oġġett usage
L-oġġett usage huwa kruċjali biex issegwi l-ispejjeż tiegħek:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Tokens tal-input u tal-output
input_tokens: Numru ta’ tokens fil-prompt tiegħek (u fl-istorja jekk qed tgħaqqad konversazzjonijiet)output_tokens: Numru totali ta’ tokens iġġenerati, inkluż ir-raġunartotal_tokens: Is-somma taż-żewġ naħat
Tokens tar-raġunar
output_tokens_details.reasoning_tokens jindika kemm-il token uża l-mudell għar-raġunar intern tiegħu. Dawn it-tokens jiġu ffiltrati iżda ma jidhrux fir-rispons testwali.
Fl-eżempju ta’ hawn fuq, minn 180 token tal-output, 120 huma għar-raġunar u biss 60 jiffurmaw ir-rispons viżibbli. Dan huwa proporzjon tipiku għal mudelli tar-raġunar.
Spiża f’nano-USD
cost_in_nano_usd jagħtik l-ispiża eżatta tat-talba. Il-konverżjoni hija sempliċi:
Spiża f'USD = cost_in_nano_usd / 1,000,000,000
Għall-eżempju tagħna: 500000 / 1,000,000,000 = 0.0005 USD ($0.0005).
Użu ta’ għodod fuq in-naħa tas-server
Meta l-mudell juża għodod integrati, l-oġġett usage jinkludi wkoll:
{
"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
}
}
Dan jippermettilek tkun taf eżattament liema għodod ġew invokati u kemm-il darba.
Estrazzjoni tat-test f’Python
Hawnhekk hawn mudell robust biex testratti l-kontenut testwali:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Iċċekkja l-istatus
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Uri l-użu
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Punti Ewlenin
- Kull rispons għandu
iduniku li jista’ jerġa’ jintuża għat-tgħaqqid jew ir-rikupru - Dejjem iċċekkja l-
statusqabel ma tuża l-kontenut - It-test jinsab f’
output[0].content[0].text reasoning_tokensjiġu ffiltrati iżda huma inviżibbli fir-risponscost_in_nano_usdmaqsum b’miljun miljun jagħti l-ispiża f’dollari