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

Chamar a API com cURL

Aula 8 de 14 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. A ferramenta universal para testar APIs
  2. O seu primeiro pedido cURL
  3. Utilizar o endpoint /v1/responses
  4. Opções úteis do cURL
  5. Ler o corpo a partir de um ficheiro
  6. Depurar erros comuns
  7. Pontos-chave

A ferramenta universal para testar APIs

O cURL é uma ferramenta de linha de comandos disponível em todos os sistemas operativos. Permite enviar pedidos HTTP sem instalar um SDK ou escrever um programa. É a ferramenta ideal para testar rapidamente um endpoint, depurar um pedido ou automatizar chamadas num script de shell.

O seu primeiro pedido cURL

Eis como enviar um pedido à API Grok com cURL:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "Hello, introduce yourself in one sentence."}
    ]
  }'

Análise do comando

  • curl https://api.x.ai/v1/chat/completions: envia um pedido POST (implícito por -d) para o endpoint
  • -H "Authorization: Bearer $XAI_API_KEY": adiciona o cabeçalho de autenticação com a sua chave
  • -H "Content-Type: application/json": indica que o corpo é JSON
  • -d '{...}': o corpo do pedido em formato JSON

Utilizar o endpoint /v1/responses

O endpoint moderno /v1/responses oferece uma sintaxe mais concisa:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Explain machine learning to me in simple terms."
  }'

Note que input substitui messages para pedidos simples. Pode passar uma string diretamente em vez de um array de mensagens.

Opções úteis do cURL

Formatar a saída JSON

A resposta bruta é difícil de ler. Utilize jq para a formatar:

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}' | jq .

A opção -s (silencioso) oculta a barra de progresso do cURL.

Extrair apenas a resposta

Para obter o texto da resposta sem os metadados:

curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }' | jq -r '.choices[0].message.content'

Ver os cabeçalhos da resposta

Para depurar limites de taxa ou erros, adicione -i para exibir os cabeçalhos HTTP:

curl -i https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Test"}'

Ler o corpo a partir de um ficheiro

Para pedidos complexos, guarde o JSON num ficheiro:

# request.json
{
  "model": "grok-4.5",
  "messages": [
    {"role": "system", "content": "You are a translator."},
    {"role": "user", "content": "Translate into French: Hello world"}
  ],
  "temperature": 0.3
}

Depois referencie-o com @:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Depurar erros comuns

  • 401 Unauthorized: chave de API inválida ou em falta. Verifique com echo $XAI_API_KEY
  • 400 Bad Request: JSON mal formado. Valide o seu JSON com jq . < request.json
  • 429 Too Many Requests: atingiu o limite de taxa. Aguarde alguns segundos
  • 404 Not Found: verifique o URL e o caminho do endpoint

Pontos-chave

  • O cURL é perfeito para testar e depurar sem escrever código
  • Autentique com -H "Authorization: Bearer $XAI_API_KEY"
  • Utilize jq para formatar e filtrar respostas JSON
  • Guarde pedidos complexos em ficheiros JSON separados