Como Obter o Campo Citations na Resposta da API do Perplexity

Quando você usa a API do Perplexity para gerar respostas com busca na web, a resposta inclui um campo citations que lista as URLs das fontes utilizadas. No entanto, muitos desenvolvedores encontram esse campo ausente ou vazio na saída da API. Isso geralmente acontece porque a requisição foi enviada sem o parâmetro necessário que ativa a coleta de citações. Este artigo explica como configurar sua chamada de API para receber o campo citations de forma confiável, abordando o header necessário, o parâmetro return_citations e o endpoint correto. Você também aprenderá a analisar a resposta e lidar com problemas comuns.

Por que o Campo Citations Está Ausente por Padrão

A API do Perplexity usa um modelo de chat completions semelhante ao da OpenAI. Por padrão, a API retorna apenas o conteúdo de texto gerado no array choices. O campo citations é uma extensão opcional que o modelo preenche apenas quando o cliente solicita explicitamente. Se você omitir o parâmetro return_citations ou defini-lo como false, a API pula a etapa de coleta de citações. Isso é proposital para manter o tempo de resposta baixo em consultas simples. Além disso, o campo citations só aparece em respostas do endpoint /chat/completions; outros endpoints como /completions não o suportam. O modelo também precisa ter a busca ativada — se você definir search_domain como none ou omitir o parâmetro search_context, o modelo pode não realizar uma busca na web e, portanto, não produzirá citações.

Passos para Habilitar o Campo Citations na Resposta da API

1. Defina o header da requisição para aceitar JSON
   Inclua o header accept: application/json em sua requisição HTTP. Isso informa à API para retornar um objeto JSON estruturado em vez de uma resposta de texto simples ou streaming. Sem esse header, a API pode retornar um texto simples ou um stream SSE que não inclui o campo citations.
2. Use a URL do endpoint correta
   Faça sua requisição POST para https://api.perplexity.ai/chat/completions. Este é o único endpoint que suporta o campo citations. Usar https://api.perplexity.ai/completions não retornará citações mesmo se você definir o parâmetro corretamente.
3. Adicione o parâmetro return_citations ao corpo da requisição
   No corpo JSON da sua requisição POST, inclua "return_citations": true. Coloque-o no nível superior do objeto JSON, junto com model e messages. Exemplo:
   {"model": "sonar-pro", "messages": [{"role": "user", "content": "Qual é a capital da França?"}], "return_citations": true}
4. Ative o contexto de busca se necessário
   Para garantir que o modelo busque na web, inclua o parâmetro search_context com um domínio válido ou defina-o como "web". Se você omitir isso, o modelo pode confiar apenas em seus dados de treinamento e pular a busca, resultando em um array citations vazio. Exemplo: "search_context": {"search_domain": "web"}
5. Analise o array citations da resposta
   Após fazer a requisição, procure pela chave citations no objeto JSON de resposta de nível superior. Ele conterá um array de URLs como strings. Exemplo de trecho de resposta:
   {"id": "...", "choices": [...], "citations": ["https://exemplo.com/fonte1", "https://exemplo.com/fonte2"]}
6. Lide com casos onde citations está vazio ou ausente
   Se o campo citations estiver totalmente ausente, verifique novamente se você definiu return_citations: true e se está usando o endpoint /chat/completions. Se o array estiver vazio, o modelo pode não ter encontrado fontes — tente reformular a consulta ou expandir o domínio de busca.

Problemas Comuns ao Recuperar Citações

Campo Citations Totalmente Ausente

Esta é a reclamação mais frequente. A causa é quase sempre uma de duas coisas: você chamou o endpoint errado (/completions em vez de /chat/completions) ou esqueceu de definir return_citations: true. Verifique a URL do endpoint e o parâmetro do corpo antes de tentar novamente. Também confirme se você está usando um modelo que suporta citações — modelos como sonar-pro e sonar-reasoning-pro suportam, mas modelos mais antigos ou personalizados podem não suportar.

Array Citations Vazio

Um array citations vazio significa que o modelo realizou uma busca mas não encontrou fontes para citar. Isso pode acontecer se a consulta for muito específica ou se o domínio de busca for restrito. Tente definir search_context.search_domain como "web" para permitir uma busca ampla. Você também pode aumentar max_tokens para dar mais espaço ao modelo para gerar citações.

Citações Aparecem no Modo Streaming mas Não no JSON

Se você estiver usando streaming (stream: true), as citações são enviadas no evento final [DONE] como um objeto JSON separado. Para capturá-las, você deve ouvir a mensagem data: [DONE] e analisar a linha data: {...} anterior que contém o campo citations. Se você definir stream: false, as citações aparecem diretamente no objeto de resposta.

Configurações da API do Perplexity: Com Citações vs Sem Citações

Item	Com Citações Habilitadas	Sem Citações
Campo na resposta	Inclui array citations com URLs	Nenhum campo citations presente
Parâmetro necessário	return_citations: true	Omitir ou definir return_citations: false
Endpoint	POST /chat/completions	Qualquer endpoint
Tempo de resposta	Ligeiramente maior devido à coleta de fontes	Mais rápido
Caso de uso	Verificação de fatos, pesquisa, trabalho acadêmico	Perguntas e respostas casuais, ferramentas internas

Ao habilitar citações, você obtém fontes verificáveis para cada resposta. Isso é especialmente útil para aplicações que exigem transparência, como plataformas educacionais, agregadores de notícias ou ferramentas de pesquisa jurídica. Sem citações, a API retorna apenas o texto gerado, o que pode ser suficiente para uso interno ou não crítico.

Agora você pode configurar qualquer cliente de API — seja em Python, JavaScript, cURL ou Postman — para recuperar o campo citations do Perplexity. Comece adicionando return_citations: true ao corpo da requisição e usando o endpoint /chat/completions. Para um controle mais avançado, explore o parâmetro search_context para ajustar quais fontes o modelo utiliza. Se precisar lidar com respostas em streaming, lembre-se de capturar o evento final que contém os dados de citações.