Crearea unui răspuns cu POST /v1/responses
Pe această pagină
Prima dumneavoastră cerere
Punctul de intrare principal pentru API-ul de Răspunsuri este endpoint-ul POST /v1/responses. Aici trimiteți prompturile și primiți răspunsuri de la modelele Grok. În această lecție, veți învăța cum să construiți și să trimiteți prima dumneavoastră cerere.
Autentificare
Toate cererile necesită un antet de autentificare care conține cheia dumneavoastră API xAI:
Authorization: Bearer $XAI_API_KEY
Vă puteți genera cheile la console.x.ai. Păstrați-le secrete – nu le includeți niciodată într-un depozit Git.
Cerere minimă
Iată cea mai simplă cerere posibilă:
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.20-0309-reasoning",
"input": "Explain what machine learning is in 3 sentences."
}'
Două câmpuri sunt suficiente:
model: ID-ul modelului Grok de utilizatinput: promptul dumneavoastră, sub formă de text simplu
Utilizarea SDK-ului Python
Dacă utilizați SDK-ul OpenAI (compatibil cu xAI), sintaxa este similară:
from openai import OpenAI
client = OpenAI(
api_key="xai-...",
base_url="https://api.x.ai/v1"
)
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explain what machine learning is in 3 sentences."
)
print(response.output[0].content[0].text)
Intrare simplă versus structurată
Parametrul input acceptă două formate.
Text simplu
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?"
}
Tablou structurat
Pentru intrări multimodale sau roluri explicite:
{
"model": "grok-4.20-0309-reasoning",
"input": [
{
"role": "user",
"content": "Analyze this image and describe what you see."
}
]
}
Formatul de tip tablou vă oferă un control mai mare, în special pentru includerea imaginilor sau specificarea unor roluri diferite.
Parametrul instructions
Pentru a defini comportamentul de sistem al modelului, utilizați instructions în loc să adăugați un mesaj de sistem în input:
{
"model": "grok-4.20-0309-reasoning",
"instructions": "You are a French cuisine expert. Always respond including a chef's tip.",
"input": "How do I make a successful béchamel?"
}
Câmpul instructions este echivalentul system prompt din Chat Completions. Acesta definește comportamentul global al modelului pe întreaga durată a conversației.
Exercițiu practic
Încercați să construiți o cerere care:
- Utilizează modelul
grok-4.20-0309-reasoning - Definește instrucțiuni de sistem pentru un asistent tehnic
- Pune o întrebare despre Python
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.20-0309-reasoning",
"instructions": "You are a senior Python developer. Give concise code examples.",
"input": "How do I read a JSON file in Python?"
}'
Puncte cheie
POST /v1/responseseste endpoint-ul principal – necesitămodelșiinputinputacceptă text simplu sau un tablou structurat cu roluriinstructionsdefinește comportamentul de sistem al modelului- Autentificarea se face prin antetul
Authorization: Bearer - SDK-ul OpenAI este compatibil cu xAI prin modificarea
base_url