API Perplexity Retorna Array de Citações Vazio: Corrigir

Ao chamar a API do Perplexity e o array de citações retornar vazio, seu aplicativo não consegue exibir as fontes da resposta. Isso quebra o valor central das respostas baseadas em pesquisa do Perplexity. O problema geralmente ocorre porque o parâmetro return_citations não está definido como true na sua requisição. Este artigo explica a causa exata e mostra como corrigir o array de citações vazio na sua integração com a API.

Por que a API Perplexity Retorna um Array de Citações Vazio

A API do Perplexity retorna um array de citações vazio quando a requisição não pede explicitamente por citações ou usa um modelo que não as suporta. O comportamento padrão da API é omitir citações, a menos que você opte por incluí-las. A causa raiz é uma de três coisas:

• O parâmetro return_citations está ausente ou definido como false.
• O modelo que você está usando é um modelo offline como sonar-small ou sonar-medium.
• O endpoint da API não suporta citações.

O Perplexity oferece duas categorias de modelos: modelos online que pesquisam na web e retornam citações, e modelos offline que geram respostas sem pesquisa em tempo real. Apenas modelos online preenchem o array de citações. A documentação da API afirma claramente que return_citations deve ser true para que o campo de citações contenha dados.

Modelos Online vs Offline

Modelos online como sonar-pro, sonar-deep-research e sonar-reasoning-pro realizam uma pesquisa na web para cada requisição. Eles retornam um array citations com URLs e trechos de texto. Modelos offline como sonar-small e sonar-medium não pesquisam na web e sempre retornam um array citations vazio. Se você precisa de citações, deve usar um modelo online.

O Parâmetro return_citations

O parâmetro return_citations é um booleano no corpo da requisição. Quando definido como true, a API inclui o campo citations na resposta. Quando omitido ou definido como false, o campo fica vazio ou não está presente. Este parâmetro só é eficaz com modelos online. Se você definir return_citations: true mas usar um modelo offline, o array de citações ainda estará vazio.

Passos para Corrigir o Array de Citações Vazio

Siga estes passos para garantir que sua requisição à API do Perplexity retorne um array de citações preenchido. Cada passo aborda uma das causas raiz descritas acima.

1. Verifique seu endpoint da API
   Certifique-se de que está chamando o endpoint /chat/completions. O endpoint antigo /completions não suporta citações. Sua URL de requisição deve ser https://api.perplexity.ai/chat/completions.
2. Selecione um modelo online
   No corpo da requisição, defina o campo model para um modelo online. Use sonar-pro para pesquisa geral, sonar-deep-research para respostas aprofundadas, ou sonar-reasoning-pro para tarefas de raciocínio. Evite sonar-small e sonar-medium.
3. Defina return_citations como true
   Adicione o parâmetro return_citations ao corpo da requisição e defina-o como true. Aqui está um exemplo de corpo JSON:

   {
"model": "sonar-pro",
"messages": [{"role": "user", "content": "Qual é a capital da França?"}],
"return_citations": true
}

4. Envie a requisição e inspecione a resposta
   Execute a chamada à API. Na resposta, procure pelo array citations. Ele deve conter objetos com campos url e title. Se o array ainda estiver vazio, verifique novamente o campo model e o valor de return_citations.
5. Verifique a compatibilidade da versão da API
   Se você estiver usando uma versão antiga da API, atualize para a mais recente. O Perplexity atualiza regularmente a API, e versões antigas podem não suportar citações. Use a versão da API 2024-01-01 ou posterior nos cabeçalhos da requisição.

Se o Array de Citações Ainda Estiver Vazio Após a Correção

Mesmo após seguir os passos acima, alguns casos extremos podem causar um array de citações vazio. Aqui estão os mais comuns e como resolvê-los.

Array de Citações Vazio para Consultas Sem Pesquisa

Algumas consultas não acionam uma pesquisa na web. Por exemplo, uma pergunta como “Quanto é 2+2?” pode ser respondida a partir do conhecimento interno do modelo. A API retornará um array de citações vazio para essas consultas. Para forçar uma pesquisa, reformule a pergunta incluindo um pedido por fontes. Exemplo: “Qual é a taxa de câmbio atual de USD para EUR e cite suas fontes.”

Array de Citações Contém URLs, mas Sem Trechos de Texto

Às vezes, a API retorna URLs sem o campo text em cada objeto de citação. Isso acontece quando a página de origem não está totalmente acessível. A correção é usar o modelo sonar-deep-research, que extrai conteúdo mais detalhado. Alternativamente, você pode buscar o conteúdo da página usando a URL fornecida.

API Retorna Array Vazio para Respostas em Streaming

Ao usar o modo streaming (stream: true), o array de citações pode aparecer vazio nos primeiros chunks. O Perplexity envia citações apenas no chunk final. Certifique-se de que seu cliente de streaming aguarde o chunk final antes de ler o campo citations. Verifique o campo finish_reason para identificar o chunk final.

Item	Modelo Online (sonar-pro)	Modelo Offline (sonar-small)
Pesquisa na web	Sim	Não
Array de citações	Preenchido com URLs e trechos	Sempre vazio
Parâmetro return_citations	Obrigatório	Ignorado
Melhor caso de uso	Respostas factuais, atuais ou com fontes	Consultas criativas ou de conhecimento geral
Endpoint da API	/chat/completions	/chat/completions

Agora você pode preencher de forma confiável o array de citações nas respostas da API do Perplexity. Comece verificando a seleção do modelo e o parâmetro return_citations. Para depuração avançada, ative o registro no seu cliente de API para inspecionar a requisição e resposta brutas. Se continuar vendo citações vazias, teste com uma consulta simples como “Quais são as últimas notícias sobre IA?” usando sonar-pro para confirmar a correção.