Criar uma resposta com POST /v1/responses
Nesta página
O seu primeiro pedido
O endpoint POST /v1/responses é o ponto de entrada principal da API de Respostas. É aqui que envia os seus prompts e recebe respostas dos modelos Grok. Nesta lição, vai aprender a construir e enviar o seu primeiro pedido.
Autenticação
Todos os pedidos exigem um cabeçalho de autenticação com a sua chave API da xAI:
Authorization: Bearer $XAI_API_KEY
Pode gerar as suas chaves em console.x.ai. Mantenha-as em segredo; nunca as coloque num repositório Git.
Pedido mínimo
Eis o pedido mais simples possível:
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."
}'
Dois campos são suficientes:
model: o ID do modelo Grok a utilizarinput: o seu prompt, como texto simples
Com o SDK Python
Se utilizar o SDK OpenAI (compatível com xAI), a sintaxe é semelhante:
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)
Entrada simples vs estruturada
O parâmetro input aceita dois formatos.
Texto simples
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?"
}
Matriz estruturada
Para entradas multimodais ou papéis explícitos:
{
"model": "grok-4.20-0309-reasoning",
"input": [
{
"role": "user",
"content": "Analyze this image and describe what you see."
}
]
}
O formato de matriz oferece-lhe mais controlo, especialmente para incluir imagens ou especificar diferentes papéis.
O parâmetro instructions
Para definir o comportamento de sistema do modelo, utilize instructions em vez de adicionar uma mensagem de sistema em 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?"
}
O campo instructions é equivalente ao system prompt nas Conclusões de Chat. Define o comportamento global do modelo para toda a conversa.
Exercício prático
Tente construir um pedido que:
- Utilize o modelo
grok-4.20-0309-reasoning - Defina instruções de sistema para um assistente técnico
- Faça uma pergunta sobre 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?"
}'
Pontos-chave
POST /v1/responsesé o endpoint principal; exigemodeleinputinputaceita texto simples ou uma matriz estruturada com papéisinstructionsdefine o comportamento de sistema do modelo- A autenticação ocorre através do cabeçalho
Authorization: Bearer - O SDK OpenAI é compatível com a xAI ao alterar o
base_url