Um pedido POST /v1/responses simples
Nesta página
Atualizado em 3 de novembro de 2026, com base nas melhores práticas e na referência da API da xAI: a temperatura está limitada a 1, e a xAI recomenda 0,7 com
top_pem 0,95. Fonte: Melhores práticas.
A sua primeira chamada bem-sucedida
Já tem a sua conta, a sua chave de API e um SDK instalado. Está na hora de enviar o seu primeiro pedido à API do Grok e compreender a estrutura da resposta. Esta lição foca-se no endpoint principal, /v1/responses, o mais moderno e o mais recomendado.
Estrutura do pedido
O endpoint POST /v1/responses aceita pelo menos dois parâmetros:
model: o ID do modelo a utilizarinput: o texto do seu pedido (ou um vetor de conteúdo para casos avançados)
Pedido mínimo em 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)
Com instruções de sistema
O parâmetro instructions permite-lhe definir o comportamento do modelo:
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 da resposta
A API devolve um objeto JSON estruturado. Eis os principais campos:
{
"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
}
}
Campos importantes
id: o ID único da resposta, útil para a recuperar mais tardestatus:completedquando a geração terminaoutput: um vetor contendo as mensagens geradasusage: contadores de tokens para monitorizar o seu consumo
Parâmetros opcionais comuns
Controlar a criatividade
response = client.responses.create(
model="grok-4.5",
input="Suggest a name for an AI startup.",
temperature=0.7, # o valor recomendado pela xAI
top_p=0.95,
)
- A API aceita uma temperatura de 0 a 2, mas limita qualquer valor superior a 1
- A xAI recomenda
temperature=0.7etop_p=0.95e desaconselha afastar-se destes valores: a qualidade costuma cair - Para mais criatividade, peça-a no prompt («sugira nomes inesperados»)
Limitar o comprimento
response = client.responses.create(
model="grok-4.5",
input="Summarize the concept of machine learning.",
max_output_tokens=200 # Limita a resposta
)
Ativar o raciocínio
Para modelos de raciocínio, ajuste o esforço de pensamento:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this problem: if 3x + 7 = 22, what is x?",
reasoning={"effort": "high"}
)
Os níveis possíveis são low, medium e high.
Continuar uma conversa
O endpoint /v1/responses suporta conversas de várias voltas através do parâmetro previous_response_id:
# Primeira mensagem
r1 = client.responses.create(
model="grok-4.5",
input="I'm building an API in Python."
)
# Segunda mensagem (o modelo lembra-se do contexto)
r2 = client.responses.create(
model="grok-4.5",
input="Which framework do you recommend?",
previous_response_id=r1.id
)
Esta abordagem é mais simples do que gerir manualmente o histórico de mensagens.
Monitorizar custos
O campo usage na resposta permite-lhe calcular o custo de cada chamada. O campo output_tokens_details.reasoning_tokens mostra quantos tokens foram usados no raciocínio interno do modelo (estes tokens são faturados, mas não aparecem na resposta).
Pontos-chave
- O endpoint
POST /v1/responsesé o mais moderno e o mais recomendado - Dois parâmetros obrigatórios:
modeleinput - A resposta encontra-se em
output[0].content[0].text - Utilize
previous_response_idpara conversas de várias voltas - O campo
usageajuda a monitorizar o seu consumo de tokens