Chamar a API com cURL
Nesta página
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
jqpara formatar e filtrar respostas JSON - Guarde pedidos complexos em ficheiros JSON separados