Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Um pedido POST /v1/responses simples

Aula 9 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A sua primeira chamada bem-sucedida
  2. Estrutura do pedido
  3. Anatomia da resposta
  4. Parâmetros opcionais comuns
  5. Continuar uma conversa
  6. Monitorizar custos
  7. Pontos-chave

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_p em 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 utilizar
  • input: 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 tarde
  • status: completed quando a geração termina
  • output: um vetor contendo as mensagens geradas
  • usage: 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.7 e top_p=0.95 e 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: model e input
  • A resposta encontra-se em output[0].content[0].text
  • Utilize previous_response_id para conversas de várias voltas
  • O campo usage ajuda a monitorizar o seu consumo de tokens