Uma chave de API da Perplexity é a credencial que você envia a cada requisição para `api.perplexity.ai`. Ela identifica seu projeto, debita do seu saldo de crédito pré-pago e define seu nível de limite de taxa. Se você nunca lidou com uma antes, nosso guia introdutório sobre o que é uma chave de API aborda o básico. Este guia cobre a parte específica da Perplexity: criando a conta, adicionando créditos, gerando a chave e enviando sua primeira requisição Sonar fundamentada de curl, Python e Apidog.
Uma observação de tempo antes de começar. A Perplexity moveu o Sonar para sua API de Agente, e o guia de início rápido oficial agora aponta para lá. O antigo endpoint de chat-completions do Sonar continuará funcionando até 27 de setembro de 2026, depois será desativado. Cada exemplo abaixo usa o endpoint atual, com uma breve nota sobre o formato legado caso você esteja mantendo código antigo.
O que você precisa antes de começar
- Uma conta Perplexity. Google, Apple, SSO ou um login por e-mail sem senha funcionam, e todos se resolvem para a mesma conta pelo endereço de e-mail.
- Um cartão de pagamento. A API é paga conforme o uso, sem assinatura, mas as requisições falham assim que seu saldo de crédito chega a zero.
- curl ou Python 3.9+ para a primeira requisição.
- Apidog se você quiser a chave armazenada como um segredo local e a requisição salva como um teste repetível.
Passo 1: faça login no console da API e crie um projeto
Vá para console.perplexity.ai e escolha um método de login. Fazer login cria uma conta Perplexity, mas não um projeto de API. Na sua primeira visita, o assistente de configuração solicita que você crie ou entre em um projeto antes de poder gerar uma chave, pois as chaves são restritas a projetos.
Abra Configurações na barra lateral esquerda e preencha o nome, endereço e detalhes fiscais da sua organização; eles aparecerão nas suas faturas. Se sua empresa já possui um projeto, peça a um administrador para adicioná-lo a ele em vez de criar um segundo. Projetos separados recebem saldos de crédito e chaves separadas, o que é útil para isolar um aplicativo de produção de um experimento.
Passo 2: adicione um método de pagamento e créditos
Abra a página de Faturamento e adicione um cartão. Conforme a documentação, adicionar um método de pagamento não cobra o cartão; ele armazena os detalhes para uso futuro. Depois, compre créditos. O saldo, os detalhes de uso por modelo e o histórico de faturas ficam todos nesta página.
Dois detalhes são importantes aqui. A API cobra de créditos pré-pagos, e se o saldo acabar, suas chaves serão bloqueadas até você recarregar. A documentação descreve essa falha como um 401, não um 402, então um aplicativo sem créditos parece um bug de autenticação à primeira vista. E ao lado de Recarga automática, clique em Alterar preferências para que o console adicione créditos automaticamente quando o saldo cair abaixo de um limite que você definir. Ative isso antes que qualquer coisa vá para produção.
A documentação não publica um valor mínimo de compra, então siga o que a página de faturamento mostra. Seu nível de uso, que define seus limites de taxa, é baseado em créditos cumulativos comprados ao longo da vida da conta, não no saldo atual.
Passo 3: gere a chave da API
Abra a página de Chaves da API no console e crie uma chave. Dê a ela um nome descritivo como dev-laptop ou prod-search-worker. Após a criação, o nome é a única forma de distinguir as chaves, pois o valor completo é exibido apenas uma vez e não pode ser recuperado novamente. Copie-o imediatamente.
Coloque a chave em uma variável de ambiente, nunca no código:
export PERPLEXITY_API_KEY="pplx-your-key-here"
No Windows, use setx PERPLEXITY_API_KEY "pplx-your-key-here" e abra um novo terminal.
Você pode criar várias chaves dentro de um projeto, então crie uma por ambiente e por serviço. Revogar uma chave é permanente, o que é o ideal quando uma chave vaza. Se você não tem certeza se uma chave já vazou para um repositório, execute um scanner de segredos sobre seu histórico git antes de rotacionar.
Passo 4: faça sua primeira requisição Sonar
O endpoint atual é POST https://api.perplexity.ai/v1/agent. A autenticação é um cabeçalho bearer padrão, Authorization: Bearer $PERPLEXITY_API_KEY. O corpo aceita um model e uma string input. O ID do modelo Sonar neste endpoint é perplexity/sonar, e adicionar a ferramenta web_search o instrui a pesquisar na web ao vivo e anexar fontes.
Pergunte algo com uma resposta real que muda ao longo do tempo:
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
"tools": [{ "type": "web_search" }]
}' | jq
A resposta contém output_text, a resposta como texto simples, e um array output com um item para cada passo que o modelo realizou. O item message contém a resposta; o item search_results lista as páginas que ele leu, cada uma com uma url, title, snippet e date. O objeto usage informa as contagens de tokens e o custo. Um status de completed significa que a execução foi concluída.
A mesma requisição em Python com o SDK oficial:
pip install perplexityai
from perplexity import Perplexity
client = Perplexity() # lê PERPLEXITY_API_KEY do ambiente
response = client.responses.create(
model="perplexity/sonar",
input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
tools=[{"type": "web_search"}],
)
print(response.output_text)
Se você preferir o SDK da OpenAI, defina base_url="https://api.perplexity.ai/v1" e chame client.responses.create() com os mesmos argumentos. O SDK o roteia para /v1/responses, que a Perplexity aceita como um alias. Presets (fast, low, medium, high, xhigh) agrupam um modelo, orçamentos de tokens e ferramentas para você; no SDK da OpenAI, você os passa através de extra_body.
Se você estiver usando o formato legado de chat-completions
Códigos mais antigos enviam messages para https://api.perplexity.ai/v1/sonar com IDs de modelo sonar, sonar-pro, sonar-reasoning-pro ou sonar-deep-research, e leem choices[0].message.content. Esse formato funciona até 27 de setembro de 2026. O guia de migração mapeia sonar para perplexity/sonar, sonar-pro para perplexity/sonar com o preset low, e deep research para o preset high. As opções search_domain_filter e search_recency_filter movem-se para dentro da ferramenta web_search como um objeto filters.
Passo 5: armazene a chave e salve a requisição no Apidog
Um curl que funciona uma vez não é um teste. Aqui está a configuração que usamos no Apidog para que a chave permaneça fora da nuvem e a requisição seja executada sob demanda.
Crie um ambiente. Adicione um ambiente chamado Perplexity com duas variáveis: base_url definido como https://api.perplexity.ai como um valor compartilhado, e PERPLEXITY_API_KEY com o valor compartilhado deixado como um placeholder e a chave real apenas no valor local. Valores locais vivem no cache do seu cliente e nunca são sincronizados com os colegas de equipe, que é o objetivo principal. Nosso guia sobre ambientes e variáveis secretas no Apidog aprofunda a divisão entre compartilhado e local.
Monte a requisição. Nova requisição, POST {{base_url}}/v1/agent. Adicione um cabeçalho Authorization: Bearer {{PERPLEXITY_API_KEY}}, defina o tipo de corpo como JSON e cole o mesmo corpo do curl acima. Selecione o ambiente Perplexity e clique em Enviar. Você deverá ver o output_text e o bloco search_results no painel de resposta.
Transforme-o em um teste. Adicione três asserções: o código de status é 200, $.status é igual a completed, e $.output_text não está vazio. Salve a requisição em um cenário de teste. Agora, qualquer pessoa da equipe pode puxar o projeto, colar sua própria chave no valor local e verificar sua configuração com um clique. Rotacionar a chave significa editar um campo, não procurar em scripts.
Se você ainda não o tem, Baixe o Apidog gratuitamente; o plano gratuito cobre quatro usuários, o suficiente para uma pequena equipe compartilhar o projeto.
Limites de taxa e o custo de uma requisição
Os limites de taxa na API de Agente escalam com seu nível de uso, e os níveis são definidos por compras cumulativas de crédito ao longo da vida, conforme a página de limites de taxa:
| Nível | Créditos comprados | Requisições por segundo | Requisições por minuto |
|---|---|---|---|
| 0 | $0 | 1 | 50 |
| 1 | $50+ | 3 | 150 |
| 2 | $250+ | 8 | 500 |
| 3 | $500+ | 17 | 1.000 |
| 4 | $1.000+ | 33 | 4.000 |
| 5 | $5.000+ | 33 | 8.000 |
Os limites usam um algoritmo de leaky-bucket, então pequenas rajadas até o limite são permitidas. Quando você o excede, a API retorna um 429 com um cabeçalho Retry-After, e as requisições rejeitadas não são cobradas. Seu nível atual é exibido na página de Preços do console, na aba de níveis de uso.
Sobre preços, um parágrafo é suficiente aqui. A página de preços lista perplexity/sonar na API de Agente a $0,25 por milhão de tokens de entrada e $2,50 por milhão de tokens de saída, mais $0,0025 por invocação de web_search. Os modelos legados de chat-completions do Sonar cobram de forma diferente: sonar a $1 por milhão de tokens de entrada e saída, mais $5 a $12 por mil requisições dependendo do tamanho do contexto de busca. Para o detalhamento completo e a perspectiva da conta Pro, consulte nosso guia da API Perplexity.
Erros comuns e como corrigi-los
401 Não Autorizado. Três causas, em ordem de probabilidade: o cabeçalho está errado (deve ser Authorization: Bearer <key>, e a variável shell deve ser exportada no mesmo terminal), a chave foi revogada, ou o saldo de crédito está zerado. Verifique a página de faturamento antes de regenerar qualquer coisa. O SDK Python levanta um AuthenticationError para isso.
400 Requisição Inválida. Geralmente um corpo no formato antigo enviado para o novo endpoint: messages em vez de input, ou um ID de modelo sonar-pro puro em /v1/agent. O SDK apresenta isso como ValidationError.
404 Não Encontrado. O caminho está errado. /v1/agent é a API de Agente e /v1/sonar é o endpoint legado de chat-completions; a documentação não lista mais nada.
429 Muitas Requisições. Você atingiu o limite do seu nível. Leia Retry-After, espere esse tempo, e então tente novamente com backoff exponencial e jitter. Comprar créditos eleva seu nível se você precisa de throughput sustentado. O guia de tratamento de erros do SDK mostra o padrão de RateLimitError.
500 ou 503. Lado do servidor. Tente novamente com um atraso; loops de nova tentativa muito apertados pioram o limite de taxa.
Perguntas Frequentes
Existe uma chave de API Perplexity gratuita?
Não há um nível gratuito documentado. A API é paga conforme o uso a partir de um saldo de crédito pré-pago, e um projeto sem créditos é bloqueado. O custo de uma primeira requisição com perplexity/sonar e uma pesquisa na web é uma fração de um centavo, então uma pequena recarga cobre muitos testes.
Qual ID de modelo devo usar para uma primeira requisição?
Use perplexity/sonar em /v1/agent com a ferramenta web_search. É a opção fundamentada de menor custo e aquela para a qual o guia de migração mapeia os IDs antigos sonar e sonar-pro. Mude para um preset como low ou medium quando quiser que a Perplexity escolha o modelo e o orçamento de pesquisa para você.
Preciso da API de Agente se eu quiser apenas resultados de busca?
Não. A API de Busca separada retorna resultados ranqueados sem executar um modelo, o que é mais barato quando você está alimentando páginas em seu próprio pipeline. Nosso passo a passo da API de Busca Perplexity mostra o formato da requisição e os filtros.
Como faço para rotacionar uma chave sem tempo de inatividade?
Crie uma segunda chave no mesmo projeto, implante-a onde a antiga era usada, confirme o tráfego na nova chave e, em seguida, revogue a antiga. A revogação é permanente, então atualize cada consumidor primeiro. A Perplexity também expõe os endpoints /generate_auth_token e /revoke_auth_token se você quiser automatizar a rotação.
Concluindo
Faça login, crie um projeto, compre créditos, gere uma chave, envie uma requisição para /v1/agent com perplexity/sonar. Esse é todo o caminho. Armazene a chave como um valor local no Apidog e salve a requisição como um teste, e a próxima pessoa da sua equipe obterá uma configuração verificável em minutos. Se você ainda tem código no endpoint de chat-completions, migre-o antes de 27 de setembro de 2026.