Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Fhem il-format tar-rispons

Lezzjoni 4 / 16 Aġġornat 30 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Anatomija ta’ rispons
  2. Struttura sħiħa
  3. Oqsma ewlenin
  4. Fhem l-oġġett usage
  5. Użu ta’ għodod fuq in-naħa tas-server
  6. Estrazzjoni tat-test f’Python
  7. Punti Ewlenin

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:

StatusTifsira
completedIr-rispons ġie ġġenerat b’suċċess
failedŻball waqt il-ġenerazzjoni
incompleteIr-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-mudell
  • function_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ġunar
  • total_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 id uniku li jista’ jerġa’ jintuża għat-tgħaqqid jew ir-rikupru
  • Dejjem iċċekkja l-status qabel ma tuża l-kontenut
  • It-test jinsab f’output[0].content[0].text
  • reasoning_tokens jiġu ffiltrati iżda huma inviżibbli fir-rispons
  • cost_in_nano_usd maqsum b’miljun miljun jagħti l-ispiża f’dollari