API Perplexity Retorna Resposta Vazia com Chave Válida: Correção

Você tem uma chave de API Perplexity válida, mas suas requisições retornam respostas vazias ou nulas. A chamada à API é bem-sucedida sem erro, mas a resposta não contém conteúdo. Esse problema geralmente ocorre devido a parâmetros ausentes ou incorretos no corpo da requisição ou nos cabeçalhos. Este artigo explica as causas raiz e fornece correções passo a passo para fazer sua API funcionar corretamente.

Por que a API Perplexity Retorna Respostas Vazias com uma Chave Válida

A API Perplexity segue o formato de chat completions compatível com OpenAI. Quando você envia uma requisição, a API espera um corpo JSON com campos obrigatórios específicos. Se algum campo obrigatório estiver ausente ou mal formatado, a API pode retornar um status 200 com um array choices vazio em vez de um erro adequado. Esse comportamento difere de muitas outras APIs que retornam um erro 400 claro.

Os dois campos ausentes mais comuns são model e stream. Sem um nome de modelo, a API não sabe qual mecanismo usar e retorna nenhuma saída. Sem definir stream como false, a API espera uma conexão streaming e pode fechar a conexão precocemente para clientes não streaming, resultando em uma resposta vazia.

Outra causa é uma URL de endpoint incorreta. O endpoint correto é https://api.perplexity.ai/chat/completions. Alguma documentação antiga aponta para https://api.perplexity.ai/v1/chat/completions, que não funciona mais e retorna resultados vazios.

Por fim, a chave da API deve ser passada no cabeçalho Authorization como Bearer SUA_CHAVE. Se a chave for passada no corpo ou como parâmetro de consulta, a API a ignora e trata a requisição como não autenticada, retornando uma resposta vazia.

Passos para Corrigir Respostas Vazias da API Perplexity

1. Verifique o endpoint da requisição
   Certifique-se de que sua requisição POST tem como alvo https://api.perplexity.ai/chat/completions. Não use /v1/ no caminho. Teste com curl: curl -X POST https://api.perplexity.ai/chat/completions -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" -d '{"model": "sonar-pro", "messages": [{"role": "user", "content": "Olá"}], "stream": false}'
2. Inclua o parâmetro model no corpo da requisição
   Adicione "model": "sonar-pro" ou "model": "sonar-small-online" ao seu corpo JSON. A Perplexity não tem um modelo padrão. Sem esse campo, a API retorna um array choices vazio.
3. Defina stream como false para requisições não streaming
   Adicione "stream": false ao corpo da requisição. Se você omitir isso, a API trata a requisição como streaming e pode não retornar dados para um cliente não streaming.
4. Verifique o formato do cabeçalho Authorization
   Use Authorization: Bearer SUA_CHAVE_DA_API. Não inclua a chave no corpo da requisição ou como parâmetro de consulta. Verifique se a chave está ativa no painel da Perplexity em API Keys.
5. Valide a estrutura do array messages
   O array messages deve conter pelo menos um objeto com os campos role e content. Os papéis suportados são system, user e assistant. Exemplo: "messages": [{"role": "system", "content": "Seja preciso"}, {"role": "user", "content": "Qual é a capital da França?"}]
6. Teste com uma requisição mínima usando curl
   Execute este comando no terminal, substituindo SUA_CHAVE pela sua chave real: curl -s -X POST https://api.perplexity.ai/chat/completions -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" -d '{"model": "sonar-small-online", "messages": [{"role": "user", "content": "Diga oi"}], "stream": false}'. Você deve ver uma resposta JSON com um array choices contendo um objeto message.

Se a API Ainda Retornar Respostas Vazias Após a Correção Principal

Resposta Contém Apenas Dados de Uso, mas Nenhum Choices

Se a resposta incluir campos usage mas choices estiver vazio, sua requisição provavelmente acionou um filtro de conteúdo. A Perplexity pode bloquear certos prompts sem retornar um erro. Revise suas mensagens em busca de conteúdo proibido. Tente um prompt neutro como “Olá” para isolar o problema.

Código de Erro 401 ou 403 em Vez de Resposta Vazia

Se você vir HTTP 401 ou 403, a chave da API é inválida ou expirou. Gere uma nova chave no painel da Perplexity em API Keys. Certifique-se de que a chave tenha as permissões corretas e não esteja revogada.

Resposta Contém Apenas um Campo ID e Object

Isso indica que a requisição chegou à API, mas o campo model estava ausente ou com erro de digitação. Verifique novamente o nome do modelo. Modelos válidos incluem sonar-pro, sonar-small-online e sonar-medium-online. O nome do modelo diferencia maiúsculas de minúsculas.

Limitação de Taxa Causa Respostas Vazias

Se você enviar muitas requisições por minuto, a Perplexity pode limitar a taxa da sua chave e retornar respostas vazias. Verifique o cabeçalho x-ratelimit-remaining na resposta da API. Aguarde 60 segundos antes de tentar novamente.

Variações de Requisição da API Perplexity: Parâmetros Corretos vs Incorretos

Item	Requisição Correta	Requisição Incorreta
Endpoint	https://api.perplexity.ai/chat/completions	https://api.perplexity.ai/v1/chat/completions
Campo model	“model”: “sonar-pro”	Ausente ou “model”: “”
Campo stream	“stream”: false	Ausente ou “stream”: true (para clientes não streaming)
Authorization	Cabeçalho: Authorization: Bearer CHAVE	Chave no corpo ou consulta
Formato messages	Array com role e content	Array com role ou content ausente

Após aplicar as correções acima, sua API deve retornar o texto esperado no campo choices[0].message.content. Se o problema persistir, verifique a página de status da Perplexity para interrupções de serviço. Você também pode ativar o log detalhado em seu código para ver a requisição exata que está sendo enviada.