Създаване на отговор с POST /v1/responses
На тази страница
Вашата първа заявка
Крайната точка POST /v1/responses е основният вход за API за отговори (Responses API). Тук изпращате своите подкани (prompts) и получавате отговори от моделите на Grok. В този урок ще научите как да изградите и изпратите първата си заявка.
Удостоверяване
Всички заявки изискват хедър за удостоверяване с вашия API ключ на xAI:
Authorization: Bearer $XAI_API_KEY
Можете да генерирате ключовете си на console.x.ai. Пазете ги в тайна – никога не ги качвайте в Git хранилище.
Минимална заявка
Ето най-простата възможна заявка:
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."
}'
Две полета са достатъчни:
model: идентификаторът на модела на Grok, който да използватеinput: вашата подкана като обикновен текст
С Python SDK
Ако използвате OpenAI SDK (съвместим с xAI), синтаксисът е подобен:
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)
Обикновен срещу структуриран вход
Параметърът input приема два формата.
Обикновен текст
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?"
}
Структуриран масив
За мультимодални входове или изрични роли:
{
"model": "grok-4.20-0309-reasoning",
"input": [
{
"role": "user",
"content": "Analyze this image and describe what you see."
}
]
}
Форматът с масив ви осигурява по-голям контрол, особено при включване на изображения или определяне на различни роли.
Параметърът instructions
За да зададете системно поведение на модела, използвайте instructions, вместо да добавяте системно съобщение в 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?"
}
Полето instructions е еквивалентно на system prompt при Chat Completions. То дефинира общото поведение на модела за целия разговор.
Практическо упражнение
Опитайте да изградите заявка, която:
- Използва модела
grok-4.20-0309-reasoning - Дефинира системни инструкции за технически асистент
- Задава въпрос относно 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?"
}'
Ключови изводи
POST /v1/responsesе основната крайна точка – тя изискваmodelиinputinputприема обикновен текст или структуриран масив с ролиinstructionsдефинира системното поведение на модела- Удостоверяването става чрез хедъра
Authorization: Bearer - OpenAI SDK е съвместим с xAI чрез промяна на
base_url