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

Criar uma resposta com POST /v1/responses

Aula 2 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. O seu primeiro pedido
  2. Autenticação
  3. Pedido mínimo
  4. Com o SDK Python
  5. Entrada simples vs estruturada
  6. O parâmetro instructions
  7. Exercício prático
  8. Pontos-chave

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 utilizar
  • input: 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:

  1. Utilize o modelo grok-4.20-0309-reasoning
  2. Defina instruções de sistema para um assistente técnico
  3. 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; exige model e input
  • input aceita texto simples ou uma matriz estruturada com papéis
  • instructions define 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