Salt la conținutul principal
Română— Alege o limbă
Meniu

O cerere POST simplă către /v1/responses

Lecția 9 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Primul dumneavoastră apel reușit
  2. Structura cererii
  3. Anatomia răspunsului
  4. Parametri opționali comuni
  5. Urmărirea costurilor
  6. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza celor mai bune practici xAI și a referinței API: temperatura este limitată la 1, iar xAI recomandă 0,7 cu top_p la 0,95. Sursă: Cele mai bune practici.

Primul dumneavoastră apel reușit

Aveți contul, cheia API și un SDK instalat. Este momentul să trimiteți prima cerere către API-ul Grok și să înțelegeți structura răspunsului. Această lecție se concentrează pe endpoint-ul principal, /v1/responses, cel mai modern și cel mai recomandat.

Structura cererii

Endpoint-ul POST /v1/responses necesită cel puțin doi parametri:

  • model: ID-ul modelului de utilizat
  • input: textul cererii dumneavoastră (sau un tablou de conținut pentru cazuri avansate)

Cerere minimă în Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.5",
    input="What's the most widely used programming language in 2026?"
)

print(response.output[0].content[0].text)

Cu instrucțiuni de sistem

Parametrul instructions vă permite să definiți comportamentul modelului:

response = client.responses.create(
    model="grok-4.5",
    instructions="You are a web development expert. Answer concisely.",
    input="What's the difference between SSR and SSG?"
)

Anatomia răspunsului

API-ul returnează un obiect JSON structurat. Iată câmpurile principale:

{
  "id": "resp-abc123",
  "object": "response",
  "status": "completed",
  "model": "grok-4.5",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The model's answer appears here."
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156,
    "total_tokens": 198
  }
}

Câmpuri importante

  • id: ID-ul unic al răspunsului, util pentru recuperarea acestuia ulterior
  • status: completed atunci când generarea s-a încheiat
  • output: un tablou care conține mesajele generate
  • usage: contoare de tokeni pentru urmărirea consumului

Parametri opționali comuni

Controlul creativității

response = client.responses.create(
    model="grok-4.5",
    input="Suggest a name for an AI startup.",
    temperature=0.7,  # valoarea recomandată de xAI
    top_p=0.95,
)
  • API-ul acceptă o temperatură între 0 și 2, dar limitează orice valoare superioară la 1
  • xAI recomandă temperature=0.7 și top_p=0.95 și sfătuiește împotriva abaterii de la acestea: calitatea scade de obicei
  • Pentru mai multă creativitate, solicitați-o în prompt („sugerați nume neașteptate“)

Limitarea lungimii

response = client.responses.create(
    model="grok-4.5",
    input="Summarize the concept of machine learning.",
    max_output_tokens=200  # Limitează răspunsul
)

Activarea raționamentului

Pentru modelele de raționament, ajustați efortul de gândire:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this problem: if 3x + 7 = 22, what is x?",
    reasoning={"effort": "high"}
)

Nivelurile posibile sunt low, medium și high.

Continuarea unei conversații

Endpoint-ul /v1/responses suportă conversații pe mai multe ture prin parametrul previous_response_id:

# Primul mesaj
r1 = client.responses.create(
    model="grok-4.5",
    input="I'm building an API in Python."
)

# Al doilea mesaj (modelul își amintește contextul)
r2 = client.responses.create(
    model="grok-4.5",
    input="Which framework do you recommend?",
    previous_response_id=r1.id
)

Această abordare este mai simplă decât gestionarea manuală a istoricului mesajelor.

Urmărirea costurilor

Câmpul usage din răspuns vă permite să calculați costul fiecărui apel. Câmpul output_tokens_details.reasoning_tokens arată câți tokeni au fost utilizați pentru raționamentul intern al modelului (acești tokeni sunt facturați, dar nu apar în răspuns).

Puncte cheie

  • Endpoint-ul POST /v1/responses este cel mai modern și cel mai recomandat
  • Doi parametri obligatorii: model și input
  • Răspunsul se află în output[0].content[0].text
  • Utilizați previous_response_id pentru conversații pe mai multe ture
  • Câmpul usage vă ajută să urmăriți consumul de tokeni