Como Começar com a API Perplexity Sonar

A API Perplexity Sonar permite integrar recursos de busca em tempo real em seus próprios aplicativos, bots ou fluxos de trabalho. Em vez de visitar o site do Perplexity, você pode enviar uma pergunta e receber uma resposta com citações de forma programática. Este artigo explica o que é a API Sonar, o que você precisa para configurá-la e como fazer sua primeira chamada de API. Você aprenderá o processo de autenticação, o formato da requisição e como lidar com a resposta.

O que a API Perplexity Sonar Faz

A API Sonar é um serviço web RESTful que oferece acesso programático aos resultados de busca do Perplexity. Quando você envia uma pergunta, a API realiza uma busca ao vivo na web, compila uma resposta e a retorna com citações. Isso é útil para criar chatbots personalizados, automatizar tarefas de pesquisa ou adicionar uma camada de busca às suas ferramentas internas.

A API usa os mesmos modelos subjacentes da interface web do Perplexity. Você pode escolher entre Sonar (o modelo padrão) e Sonar Pro (o modelo de maior capacidade com raciocínio mais profundo). Ambos os modelos suportam janelas de contexto de até 200.000 tokens, permitindo incluir documentos longos ou históricos de conversa em suas requisições.

Antes de fazer chamadas, você precisa de três coisas: uma conta no Perplexity, uma chave de API e uma ferramenta para enviar requisições HTTP. A ferramenta pode ser cURL, Python com a biblioteca requests, Postman ou qualquer cliente HTTP de sua preferência.

Pré-requisitos

Você deve ter uma conta no Perplexity com uma assinatura ativa que inclua acesso à API. Em maio de 2025, o acesso à API está disponível no plano Pro e superiores. Contas gratuitas não podem gerar chaves de API. Você também precisa de familiaridade básica com requisições HTTP e formatação JSON.

Passos para Gerar sua Chave de API e Fazer sua Primeira Requisição

Siga estes passos para obter sua chave de API e enviar uma consulta para a API Sonar. O processo é idêntico para Windows, macOS e Linux.

1. Faça login na sua conta do Perplexity
   Abra um navegador e acesse perplexity.ai. Entre com a conta que possui uma assinatura Pro ativa.
2. Navegue até as configurações da API
   Clique na sua foto de perfil ou avatar no canto superior direito. Selecione Configurações no menu suspenso. Na barra lateral esquerda, clique em API.
3. Gere uma nova chave de API
   Na página da API, clique no botão Gerar Chave de API. Uma string de chave aparecerá. Copie-a imediatamente e armazene em um local seguro. O Perplexity não mostra a chave completa novamente após você sair da página.
4. Abra seu cliente HTTP
   Abra uma janela de terminal para cURL ou sua ferramenta de teste de API preferida. Este exemplo usa cURL porque está disponível em todas as plataformas.
5. Construa a requisição POST
   Cole o seguinte comando no terminal. Substitua SUA_CHAVE_API pela chave que você copiou. Substitua o texto da consulta pela sua própria pergunta.

   curl --request POST \
--url https://api.perplexity.ai/chat/completions \
--header 'Authorization: Bearer SUA_CHAVE_API' \
--header 'Content-Type: application/json' \
--data '{
"model": "sonar",
"messages": [
{
"role": "user",
"content": "Qual é a população atual de Tóquio?"
}
]
}'

6. Envie a requisição e analise a resposta
   Pressione Enter. A API retorna um objeto JSON. O texto da resposta aparece no campo choices[0].message.content. O array citations contém URLs das fontes utilizadas.

Usando Sonar Pro em vez de Sonar

Para usar o modelo de maior capacidade, altere o campo model de "sonar" para "sonar-pro". O Sonar Pro suporta raciocínio mais complexo, contexto mais longo e retorna citações mais detalhadas. A estrutura da requisição é idêntica.

Adicionando Instruções de Sistema

Você pode orientar o comportamento da API incluindo uma mensagem de sistema antes da mensagem do usuário. Adicione um objeto ao array messages com "role": "system". Por exemplo:

{
"role": "system",
"content": "Você é um assistente de pesquisa. Responda de forma concisa e sempre cite a fonte mais recente."
}

Erros Comuns e Como Evitá-los

Novos usuários frequentemente encontram alguns problemas recorrentes. Conhecê-los economizará tempo durante a configuração.

Erro 401 Não Autorizado

Este erro significa que sua chave de API está ausente, expirada ou inválida. Verifique se a chave foi copiada corretamente no cabeçalho Authorization. Certifique-se de que a chave é da conta com uma assinatura Pro ativa. Se a chave foi gerada em um plano antigo que não suporta mais acesso à API, gere uma nova chave após fazer upgrade.

Erro 400 Requisição Inválida – Nome do Modelo Inválido

O nome do modelo deve ser exatamente sonar ou sonar-pro. Erros de digitação como sonar-pro com espaço ou Sonar com S maiúsculo causam um erro 400. Verifique a grafia exata no payload JSON.

Limites de Taxa Excedidos

O Perplexity impõe limites de taxa com base no seu plano de assinatura. Se você receber uma resposta 429 Muitas Requisições, reduza a frequência das chamadas. O plano Pro normalmente permite 10 requisições por minuto. Consulte a documentação da API para os limites mais recentes.

Citações Vazias ou Incompletas

Algumas consultas retornam respostas com poucas ou nenhuma citação. Isso acontece quando o modelo depende de conhecimento interno para fatos muito comuns. Para forçar uma busca, inclua o parâmetro search_domain_filter no corpo da requisição. Por exemplo:

"search_domain_filter": ["perplexity.ai"]

Item	Sonar	Sonar Pro
Nome do modelo	sonar	sonar-pro
Janela de contexto	Até 200.000 tokens	Até 200.000 tokens
Detalhe das citações	URLs padrão	URLs com trechos inline
Caso de uso ideal	Consultas factuais rápidas	Tarefas de pesquisa complexas
Custo por requisição	Menor	Maior

Agora você pode enviar consultas para a API Perplexity Sonar de qualquer aplicativo que suporte requisições HTTP. Comece com um comando cURL simples para verificar sua configuração e, em seguida, passe para a integração da API em seu próprio código. Para uso avançado, explore parâmetros como temperature para criatividade na resposta e max_tokens para limitar o tamanho da resposta. A documentação da API no site do Perplexity lista todos os parâmetros disponíveis.