Modo de Foco do Perplexity Não Pode Ser Alterado em Chamadas de API: Solução Alternativa

Se você usa a API do Perplexity para automatizar pesquisas ou criar aplicativos, pode ter notado que a configuração do Modo de Foco não muda quando você a especifica na sua solicitação de API. Isso significa que suas chamadas de API sempre retornam resultados do domínio de pesquisa padrão, ignorando os parâmetros destinados a alternar para os modos Acadêmico, Escrita, Matemática, Vídeo ou outros. A causa raiz é que a API do Perplexity atualmente não suporta a seleção dinâmica do Modo de Foco por meio de parâmetros de solicitação padrão. Este artigo explica por que essa limitação existe e fornece uma solução alternativa concreta usando endpoints de API alternativos e modificações na consulta para alcançar o mesmo resultado.

Por que a API do Perplexity Ignora o Parâmetro Modo de Foco

A API do Perplexity foi projetada principalmente para realizar pesquisas na web e gerar respostas usando modelos de linguagem de grande porte. O recurso Modo de Foco disponível na interface web do Perplexity é uma configuração do lado do cliente que ajusta o domínio de pesquisa e o comportamento do modelo para casos de uso específicos. Quando você envia uma chamada de API, o servidor processa a solicitação com base na configuração padrão do endpoint. A especificação da API não inclui um parâmetro focus_mode dedicado no esquema da solicitação. Em vez disso, a API usa um parâmetro diferente chamado search_focus que não está documentado no guia de início rápido oficial.

O parâmetro search_focus é uma substituição no nível da consulta que informa ao mecanismo de busca subjacente para priorizar resultados de um domínio ou tipo de fonte específico. Este parâmetro é separado da seleção do modelo e não altera o modelo de linguagem subjacente. A interface web usa este mesmo parâmetro internamente quando você alterna os Modos de Foco. Ao usar search_focus em suas chamadas de API, você pode replicar o comportamento do Modo de Foco sem depender do campo focus_mode não suportado.

Passos para Alterar o Modo de Foco em Chamadas de API Usando search_focus

Os passos a seguir mostram como modificar sua solicitação de API para incluir o parâmetro search_focus. Você pode usar qualquer linguagem de programação ou ferramenta que suporte solicitações HTTP POST. O exemplo usa cURL para maior clareza.

1. Identifique seu endpoint de API e autenticação
   Sua chamada de API deve ter como alvo o endpoint correto. Use https://api.perplexity.ai/chat/completions para o endpoint baseado em chat. Inclua sua chave de API no cabeçalho Authorization como Bearer SUA_CHAVE_API. Sem uma chave válida, a solicitação falhará com um erro 401.
2. Adicione o parâmetro search_focus ao corpo da solicitação
   Dentro do corpo da solicitação JSON, inclua o campo search_focus no mesmo nível que model e messages. Defina seu valor para uma das strings suportadas: academic, writing, math, video, web ou social. Por exemplo: "search_focus": "academic". Isso informa à API para retornar resultados de fontes acadêmicas.
3. Envie a solicitação modificada
   Use uma ferramenta como cURL para testar a alteração. Um comando cURL completo se parece com isto:
   curl -X POST https://api.perplexity.ai/chat/completions -H "Authorization: Bearer SUA_CHAVE_API" -H "Content-Type: application/json" -d '{ "model": "sonar-pro", "messages": [{"role": "user", "content": "Qual é a pesquisa mais recente sobre computação quântica?"}], "search_focus": "academic" }'
4. Verifique se a resposta inclui fontes específicas do domínio
   Confira o JSON de resposta para o array sources. Com search_focus: academic, as fontes devem incluir domínios como arxiv.org, pubmed.ncbi.nlm.nih.gov ou scholar.google.com. Se as fontes ainda mostrarem domínios gerais da web como wikipedia.org ou news.com, o parâmetro pode estar escrito incorretamente ou a versão do endpoint pode não suportá-lo.

Valores Suportados de search_focus e Seus Efeitos

Os seguintes valores para search_focus correspondem aos Modos de Foco na interface web:

• academic – Retorna resultados de periódicos revisados por pares, pré-impressões e bancos de dados acadêmicos.
• writing – Retorna resultados de blogs, comunidades de escrita e guias de estilo.
• math – Retorna resultados de sites e fóruns focados em matemática, como o Math Stack Exchange.
• video – Retorna resultados de plataformas de vídeo como YouTube e Vimeo.
• web – Comportamento padrão. Retorna resultados gerais de pesquisa na web.
• social – Retorna resultados de plataformas de mídia social como Reddit e Twitter.

Se search_focus Não Funcionar para o Seu Caso de Uso

“Preciso do Modo de Foco Reddit ou Notícias”

O parâmetro search_focus não inclui um valor dedicado reddit ou news. Para obter resultados semelhantes, modifique o conteúdo da mensagem do usuário. Adicione site:reddit.com ou site:news.yahoo.com à sua consulta. Por exemplo: "content": "site:reddit.com melhores laptops baratos 2025". Isso força o mecanismo de busca a retornar apenas resultados do domínio especificado. Este método funciona para qualquer domínio que você queira segmentar.

“A API retorna um erro quando adiciono search_focus”

Se sua chamada de API retornar um erro 400 Bad Request após adicionar search_focus, verifique se você está usando o endpoint correto. O endpoint /chat/completions suporta search_focus a partir da versão v2 da API. Se você estiver usando um endpoint mais antigo, como /v1/completions, atualize para https://api.perplexity.ai/chat/completions. Verifique também se seu JSON é válido: use aspas duplas, não aspas simples, e certifique-se de que não há vírgulas finais.

“As fontes ainda mostram resultados gerais da web”

Isso pode acontecer se o valor de search_focus estiver escrito incorretamente ou se o modelo que você está usando não suportar filtragem de domínio. Modelos como sonar-pro e sonar-reasoning-pro suportam search_focus. Modelos chamados mixtral ou llama podem não suportar. Mude para um modelo suportado e verifique a ortografia: academic, não academics; writing, não write.

Modo de Foco da API do Perplexity: Padrão vs. Substituição por search_focus

Item	Comportamento Padrão da API	Com o Parâmetro search_focus
Seleção do Modo de Foco	Sempre usa o modo Web	Pode usar Acadêmico, Escrita, Matemática, Vídeo, Social
Nome do parâmetro	Nenhum (ignora focus_mode)	search_focus
Endpoints suportados	Todos os endpoints	Apenas /chat/completions
Restrição de domínio	Sem restrição	Restringe a tipos de fonte específicos
Modificação da consulta necessária	Não	Não, mas pode ser combinado com o prefixo site: para modos não suportados

A API do Perplexity não suporta alterações no Modo de Foco por meio do parâmetro padrão focus_mode. Use search_focus para modos suportados ou adicione consultas com site: para domínios personalizados. Sempre teste com um modelo suportado e o endpoint correto. Para a lista mais atualizada de valores de search_focus, consulte a documentação da API do Perplexity na seção search_focus.