API Perplexity não permite definir Modo de Foco: Solução Alternativa

Ao usar a API Perplexity, você pode perceber que não há um parâmetro direto para definir o Modo de Foco. A API não expõe um campo focus_mode, então não é possível alternar programaticamente entre os domínios de busca Web, Acadêmico, Escrita, Matemática, Vídeo ou Social. Essa limitação significa que suas chamadas de API sempre usarão o domínio de busca padrão, que é o Web. Este artigo explica por que o Modo de Foco está ausente na API e fornece uma solução prática para simular pesquisas específicas de domínio usando engenharia de prompt e formatação de consulta.

Por que a API Perplexity não tem um parâmetro de Modo de Foco

A interface web do Perplexity inclui um menu suspenso de Modo de Foco que permite restringir os resultados da pesquisa a um domínio específico. Esse recurso é implementado como um filtro do lado do cliente no aplicativo web. A API, no entanto, é projetada para ser um mecanismo de busca e resposta de uso geral. Ela não inclui um parâmetro para Modo de Foco porque o caso de uso principal da API é fornecer respostas de toda a web.

A equipe da API confirmou que o Modo de Foco não faz parte da especificação pública da API. Em vez disso, a API usa o parâmetro model para selecionar o modelo de linguagem subjacente. Modelos diferentes podem ter pontos fortes diferentes. Por exemplo, sonar-pro é otimizado para pesquisa aprofundada, enquanto sonar-reasoning é melhor para raciocínio passo a passo. No entanto, nenhum desses modelos restringe o domínio de busca a uma categoria específica como Acadêmico ou Vídeo.

Isso significa que, se você precisar de resultados de pesquisa específicos de domínio por meio da API, deve implementar uma solução alternativa do seu lado. A solução envolve três técnicas: selecionar o modelo certo, criar um prompt focado e filtrar a resposta da API por domínio de origem.

Passos para Simular o Modo de Foco Usando Engenharia de Prompt

Siga estes passos para instruir a API Perplexity a retornar resultados que imitem um Modo de Foco específico. O segredo é incluir uma instrução clara de domínio no início da sua consulta.

1. Selecione o modelo apropriado
   Escolha um modelo que se alinhe ao domínio de foco. Para consultas de pesquisa pesada, use sonar-pro. Para busca geral na web, use sonar-small-online. Defina o parâmetro model na sua requisição à API. Exemplo: "model": "sonar-pro".
2. Adicione uma instrução de Modo de Foco ao prompt
   Anteceda sua consulta com uma frase que diga ao modelo para restringir sua busca. Para o modo Acadêmico, escreva: Modo de foco: Acadêmico. Pesquise apenas fontes acadêmicas. Para o modo Escrita: Modo de foco: Escrita. Pesquise apenas recursos de escrita e gramática. Para o modo Matemática: Modo de foco: Matemática. Pesquise apenas fontes matemáticas. Para o modo Vídeo: Modo de foco: Vídeo. Pesquise apenas transcrições e descrições de vídeos. Para o modo Social: Modo de foco: Social. Pesquise apenas postagens em redes sociais.
3. Defina o prompt do sistema
   Se seu cliente de API suportar um prompt de sistema, defina-o como: Você é um assistente de busca que retorna apenas resultados do domínio especificado. Siga exatamente a instrução do Modo de Foco. Isso reforça a restrição de domínio.
4. Faça a requisição à API
   Envie sua requisição com os parâmetros acima. Por exemplo, usando curl:
   curl -X POST https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{"model": "sonar-pro", "messages": [{"role": "system", "content": "Você é um assistente de busca que retorna apenas resultados do domínio especificado. Siga exatamente a instrução do Modo de Foco."}, {"role": "user", "content": "Modo de foco: Acadêmico. Qual é a pesquisa mais recente sobre computação quântica?"}]}'
5. Verifique as fontes da resposta
   Analise o array sources na resposta da API. Filtre as fontes para manter apenas aquelas que correspondem ao domínio desejado. Para o modo Acadêmico, mantenha fontes com domínios terminados em .edu, .org, ou de editoras acadêmicas conhecidas como nature.com ou sciencedirect.com. Descarte as demais.
6. Reconsulte se os resultados não forem satisfatórios
   Se o modelo ignorar a instrução do Modo de Foco, ajuste o prompt. Torne-o mais explícito: IMPORTANTE: Pesquise apenas artigos acadêmicos e publicações científicas. Não use fontes gerais da web. Em seguida, repita a requisição.

Solução Alternativa Adicional: Use os Endpoints da API da Interface Web

Uma solução alternativa é chamar os mesmos endpoints de API que a interface web do Perplexity usa quando você seleciona um Modo de Foco. Esta é uma abordagem não oficial e pode quebrar se a interface web mudar. Use por sua conta e risco.

1. Abra as ferramentas de desenvolvedor do navegador
   Abra o Perplexity no seu navegador. Pressione F12 para abrir as Ferramentas do Desenvolvedor. Vá para a aba Rede.
2. Selecione um Modo de Foco
   Clique no menu suspenso de Modo de Foco e escolha, por exemplo, Acadêmico. Observe a requisição de rede que aparece.
3. Copie os detalhes da requisição
   Clique com o botão direito na requisição e selecione Copiar > Copiar como cURL. Isso fornece a requisição completa com cabeçalhos e corpo. Observe que a requisição inclui um campo focus_mode no payload JSON.
4. Replique a requisição no seu código
   Use o comando cURL copiado como modelo para suas chamadas de API. Substitua o token de sessão pelo seu próprio. Mantenha o campo focus_mode definido com o valor desejado.
5. Lide com a autenticação
   Você precisará de um cookie ou token de sessão válido. Essa abordagem contorna a API oficial e usa a API interna da interface web. Não é suportada pelo Perplexity e pode parar de funcionar após atualizações.

Se a Solução Alternativa Não Funcionar

O Modelo Ignora a Instrução do Modo de Foco

Se o modelo retornar resultados gerais da web apesar do seu prompt, a instrução pode estar muito fraca. Reforce-a adicionando a frase CRÍTICO no início. Além disso, defina o parâmetro temperature como 0 para reduzir a criatividade. Exemplo: "temperature": 0. Isso força o modelo a seguir a instrução de forma mais rigorosa.

A Resposta Não Contém Fontes

Alguns modelos da API, como sonar-reasoning, podem não retornar um array sources. Mude para um modelo que o faça, como sonar-pro ou sonar-small-online. Consulte a documentação da API para a lista de modelos que suportam citações de fontes.

A Filtragem Remove Todas as Fontes

Se seu filtro remover todas as fontes, o modelo pode não ter encontrado resultados específicos do domínio. Amplie seus critérios de filtro. Para o modo Acadêmico, considere incluir domínios .gov e servidores de preprint como arxiv.org. Para o modo Vídeo, inclua youtube.com e vimeo.com. Ajuste o filtro e faça uma nova consulta.

Modelos da API Perplexity vs Simulação do Modo de Foco

Item	Modelo da API (sonar-small-online)	Modelo da API (sonar-pro)
Melhor para Modo de Foco	Busca geral na web (modo Web padrão)	Acadêmico, Escrita, Matemática (pesquisa aprofundada)
Suporte a citação de fontes	Sim	Sim
Adesão à instrução do prompt	Moderada	Forte
Custo por 1M tokens	$0,20	$5,00
Caso de uso	Respostas rápidas, conhecimento geral	Pesquisa aprofundada, consultas específicas de domínio

A API Perplexity não suporta o Modo de Foco diretamente. Você pode simulá-lo selecionando o modelo certo, criando um prompt preciso e filtrando as fontes da resposta. Para melhores resultados, use sonar-pro para consultas acadêmicas ou de pesquisa aprofundada e sonar-small-online para buscas gerais na web. Sempre teste seus prompts com algumas consultas de exemplo para verificar se o modelo segue a instrução de domínio. Se a solução alternativa falhar, considere usar os endpoints internos da API da interface web, mas esteja preparado para possíveis mudanças que quebrem a funcionalidade.