API da Perplexity AI: Acesso, Preços, Integração e Guia de Produção

API da Perplexity AI: Acesso, Preços, Integração e Guia de Produção

Última verificação com base na documentação da Perplexity: 24 de outubro de 2026.

A API da Perplexity AI deixou de ser uma única e indiferenciada “API de pesquisa-chat”. Agora, ela tem interfaces distintas para respostas de agentes fundamentadas na web, roteamento de modelos de pesos abertos, pesquisa bruta, embeddings e decisões tipadas. Escolha a interface que corresponde à tarefa antes de escrever código: ela determina o endpoint, o método do SDK, a unidade de preço, o limite de taxa e o que você precisa registrar em produção.

Para a maioria dos novos recursos de pesquisa ou assistente, comece com a Agent API. Ela segue o formato OpenAI Responses, pode usar pesquisa na web e retorna uma saída estruturada com fontes. Use a Orchestrator API quando seu código existente do OpenAI Chat Completions precisar de acesso ao catálogo de modelos de pesos abertos. Use Search quando precisar de resultados classificados sem uma resposta de LLM.

A resposta curta: qual API da Perplexity você deve usar?

Essa distinção é a escolha de design mais importante da API da Perplexity AI. A visão geral atual da Perplexity descreve a Agent API como uma API compatível com OpenAI Responses e fundamentada na web; sua Orchestrator API é uma interface de compatibilidade separada para modelos de pesos abertos hospedados. Leia a visão geral da Perplexity.

Obtenha acesso à API da Perplexity AI

1. Crie uma conta no Console da API da Perplexity.
2. Gere uma chave na página API Keys.
3. Armazene-a apenas no servidor ou no gerenciador de segredos da sua implantação.
4. Defina PERPLEXITY_API_KEY no ambiente de execução — não em código do navegador, git, exemplos ou logs.
5. Adicione faturamento antes de enviar tráfego de produção. A Perplexity documenta a cobrança de API conforme o uso, sem exigência de assinatura; consulte a página de preços atual antes do lançamento, pois as taxas de modelos e ferramentas podem mudar.

No macOS ou Linux, defina o segredo sem imprimi-lo:

export PERPLEXITY_API_KEY="replace-in-your-secret-manager"
test -n "$PERPLEXITY_API_KEY" && echo "PERPLEXITY_API_KEY is set"

O comando final confirma deliberadamente a presença sem expor o valor. A Perplexity aconselha explicitamente não imprimir chaves nem mesmo fragmentos delas na saída do terminal. Para o restante da sua aplicação, siga a mesma regra: oculte cabeçalhos Authorization, alterne chaves comprometidas e dê a cada ambiente sua própria credencial. Combine isso com um fluxo de trabalho seguro de gerenciamento de chaves de API antes de adicionar tráfego de clientes.

Integre a Agent API com o SDK da OpenAI

A Agent API é a interface correta da API da Perplexity AI quando seu produto precisa de uma resposta fundamentada na web, citações, uso de ferramentas ou uma resposta que possa continuar entre turnos. A Perplexity documenta a configuração do SDK da OpenAI como base_url="https://api.perplexity.ai/v1", usando client.responses.create().

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai/v1",
)

response = client.responses.create(
    model="perplexity/sonar",
    input="What changed in the last 30 days for this topic? Cite primary sources.",
    tools=[{"type": "web_search"}],
    max_output_tokens=600,
)

print(response.output_text)

O endpoint canônico é POST /v1/agent; o SDK da OpenAI envia POST /v1/responses, que a Perplexity aceita como um alias. Isso é compatível na camada Responses, não uma promessa de que todas as opções de Chat Completions sejam mapeadas de forma limpa. O guia de compatibilidade com OpenAI da Perplexity é a fonte oficial para campos de solicitação e resposta compatíveis.

Dois detalhes de produção são importantes aqui:

• A pesquisa na web é opcional. Uma solicitação somente com model e input usa o conhecimento do modelo e não retorna citações; use um nível de esforço ou uma ferramenta web_search quando atualidade e fontes forem importantes.
• Mantenha a estrutura output, não apenas output_text, no limite da sua aplicação. Citações, atividade de ferramentas, status, uso e o ID da resposta são dados operacionais — não decoração para a UI.

Antes de fixar um identificador de modelo no código, consulte GET /v1/models no seu fluxo de implantação ou analise o catálogo atual de modelos da Agent API. A Perplexity documenta esse endpoint em um formato compatível com OpenAI, o que o torna útil para listas de permissões e verificações de lançamento.

Use a Orchestrator API quando precisar de compatibilidade com Chat Completions

A API da Perplexity AI tem um segundo caminho compatível com OpenAI para uma finalidade diferente. A Orchestrator API usa o formato de Chat Completions e uma URL base diferente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai/orchestrator/v1",
)

completion = client.chat.completions.create(
    model=os.environ["PPLX_ORCHESTRATOR_MODEL"],
    max_tokens=500,
    messages=[
        {"role": "user", "content": "Summarize these notes in five bullets."}
    ],
)

print(completion.choices[0].message.content)

Use uma variável de ambiente para o ID do modelo e valide-a na CI ou em uma verificação de lançamento. A disponibilidade do catálogo, os aliases e as tabelas de preços mudam com mais frequência do que o código da sua aplicação deveria mudar. O principal erro a evitar é tratar a Agent API e a Orchestrator API como intercambiáveis:

• Agent API: https://api.perplexity.ai/v1 + responses.create().
• Orchestrator API: https://api.perplexity.ai/orchestrator/v1 + chat.completions.create().

Se o seu objetivo é uma resposta atualizada e com citações, não mude para Chat Completions apenas porque esse cliente é familiar. Se o seu objetivo é uma migração direta para OpenAI Chat Completions do catálogo hospedado de modelos de pesos abertos, não a aponte para a URL base da Agent. O guia de início rápido da Perplexity mostra ambos os padrões.

Preços da API da Perplexity AI: calcule a solicitação inteira

A forma prática de orçar a API da Perplexity AI é separar as cobranças de tokens das cobranças de ferramentas ou solicitações. A tabela de preços exata é dinâmica e específica por modelo; portanto, use a página de preços como uma entrada para a implantação — não como um número que você copia para um slide uma vez por trimestre.

As taxas acima foram verificadas em 24 de outubro de 2026. A página oficial de preços e o catálogo de modelos da Agent API devem ser verificados novamente antes de definir uma margem, cota de cliente ou alerta de orçamento.

Uma fórmula útil para planejamento é:

request_cost =
  (input_tokens / 1,000,000 × input_rate) +
  (output_tokens / 1,000,000 × output_rate) +
  (cache_read_tokens / 1,000,000 × cache_read_rate) +
  tool_invocations × tool_rate +
  search_requests × search_request_rate

Não estime uma resposta pesquisada apenas com base nos tokens de saída. Os fluxos de trabalho de agentes podem usar contexto de entrada, tokens de saída/raciocínio e chamadas de ferramentas. Armazene cada uma dessas dimensões com o ID do seu locatário, nome do recurso, modelo solicitado, modelo final e ID da resposta. Esse mesmo modelo de eventos torna as comparações de preços de modelos de IA muito mais significativas do que comparar apenas os preços de tabela.

Crie um fluxo de trabalho da API da Perplexity AI pronto para produção

1. Torne a superfície da API uma decisão explícita de produto

Defina um pequeno adaptador por superfície, como perplexity_agent, perplexity_search e perplexity_orchestrator. Não esconda seus diferentes tipos de resposta atrás de uma função genérica chat() até decidir o que acontece com citações, resultados de pesquisa, uso e eventos de ferramentas.

Para uma resposta de pesquisa voltada ao cliente, seu adaptador deve retornar pelo menos:

answer_text, citations, response_id, status, requested_model,
served_model, input_tokens, output_tokens, tool_calls, cost, latency_ms

Para Search bruto, retorne os resultados separadamente de qualquer síntese posterior. Isso preserva a proveniência e possibilita alterar o modelo de redação sem mudar silenciosamente o provedor de pesquisa.

2. Trate as citações como dados que você deve preservar

Quando a sua solicitação à API da Perplexity AI usa pesquisa na web, mostre as fontes citadas ao lado da afirmação que elas sustentam. Salve a URL da fonte retornada, o título quando fornecido e o ID da resposta usado para criar a resposta. Uma resposta amigável sem fontes verificáveis não é suficiente para um recurso de pesquisa, agente de suporte ou fluxo de trabalho interno de decisão.

Defina sua política antes do lançamento:

• Você exige pelo menos uma fonte primária para uma resposta factual?
• Você removerá uma afirmação quando nenhuma citação a sustentar?
• Um usuário pode abrir a URL citada antes de agir com base na resposta?
• Por quanto tempo você retém os metadados da fonte e os registros de resposta?

3. Planeje o orçamento para janelas móveis de taxa, não para um único número de “solicitações por minuto”

A API Agent da Perplexity documenta um limite de solicitações para toda a organização, compartilhado entre chamadas do Agent, consultas de status, operações de cancelamento/retomada e downloads de arquivos. Ela também documenta limites de tokens por modelo em janelas móveis de minuto e hora. Consultas de status não são gratuitas: em uma camada inferior, consultar uma solicitação assíncrona uma vez por segundo pode consumir toda a franquia de solicitações.

Para respostas 429, respeite Retry-After. Para erros overloaded relacionados à capacidade, aplique backoff exponencial com jitter e use uma lista de fallback documentada somente quando o produto puder aceitar com segurança um modelo diferente. Não tente novamente erros de autenticação, validação ou configuração de cota como se fossem transitórios. Consulte as orientações sobre limites de taxa e camadas de uso da Perplexity para ver os limites atuais e a semântica das respostas.

Pseudocódigo para uma política de novas tentativas limitada:

for attempt in range(3):
    try:
        return call_perplexity()
    except RateLimitError as error:
        wait_seconds = retry_after_or_jittered_backoff(error, attempt)
        sleep(wait_seconds)
    except TransientCapacityError:
        sleep(jittered_backoff(attempt))

raise ServiceTemporarilyUnavailable()

Mantenha o número de tentativas pequeno, use um prazo de ponta a ponta e deixe visível o estado de fallback do chamador. Tentativas que transformam uma solicitação de pesquisa lenta em um indicador de carregamento de 90 segundos não são confiabilidade.

4. Registre dados suficientes para depurar custo, qualidade e atualidade em conjunto

Acompanhe o ID da solicitação, a família de endpoint, o modelo, o nível de esforço, a lista de ferramentas, o tempo até o primeiro token, o tempo de conclusão, as dimensões de tokens, a contagem de chamadas de ferramentas, o status HTTP, a contagem de tentativas e uma classificação segura de erros. Para respostas com citações, acompanhe a contagem de citações e os domínios das fontes. Para Search, acompanhe a contagem de consultas e a contagem de resultados.

Isso fornece as evidências para responder a perguntas como: “A latência aumentou porque habilitamos a pesquisa?”, “Qual locatário está gastando em sessões sandbox?” e “Um fallback melhorou a disponibilidade, mas reduziu a cobertura de citações?” Para uma arquitetura mais geral, consulte o guia de gateway de API de IA e o guia de limites de taxa de LLM.

5. Planeje uma migração do Sonar se você tiver código legado

As orientações atuais de migração da Perplexity dizem que o suporte a Sonar Chat Completions terminou em 27 de setembro de 2026. Elas recomendam a API Agent para novos projetos; as solicitações legadas síncronas e de streaming estão sendo reformuladas gradualmente, enquanto as solicitações assíncronas do Sonar não são mais suportadas. Se você ainda chama um endpoint do Sonar, teste agora um adaptador da API Agent em vez de descobrir uma quebra assíncrona em produção. Leia o guia de migração.

API da Perplexity direta ou um gateway multmodelo separado?

Use uma integração direta com a API da Perplexity AI quando o recurso depender de Agent, Search, citações, níveis de esforço ou comportamento de API específicos da Perplexity. Isso mantém claro o contrato de produção.

Use um gateway multmodelo separado somente para os modelos e endpoints que esse gateway lista atualmente como suportados. Por exemplo, a Flatkey documenta uma URL base compatível com OpenAI em https://router.flatkey.ai/v1 para seu catálogo suportado e um painel de uso no nível da solicitação. Seu diretório público de modelos deve ser verificado em tempo real antes de presumir que um provedor ou modelo está disponível. Comece com o início rápido da API da Flatkey.

Para equipes que precisam de ambos, use dois clientes explícitos:

Não roteie um endpoint direto da Perplexity por outro serviço, a menos que a documentação atual dele ofereça suporte explícito a essa rota. O objetivo não é forçar todas as chamadas por uma única camada; é preservar a capacidade e o comportamento de faturamento dos quais seu recurso realmente depende.

Checklist de lançamento em produção

• [ ] Cada recurso selecionou intencionalmente Agente, Orquestrador, Pesquisa, Embeddings ou Decisões.
• [ ] As chaves de API ficam no lado do servidor, têm escopo por ambiente e estão ausentes dos bundles do cliente e dos logs.
• [ ] A URL base do Agente (/v1) e a URL base do Orquestrador (/orchestrator/v1) não são confundidas.
• [ ] Os IDs dos modelos e os cartões de preços atuais são validados em uma verificação de lançamento.
• [ ] A pesquisa na web é ativada explicitamente apenas quando informações atuais com citações são úteis.
• [ ] As respostas com citações retêm os metadados das fontes e um ID de resposta.
• [ ] Os eventos de custo incluem dimensões de tokens e contagens de invocações de ferramentas ou de pesquisa.
• [ ] O 429 respeita Retry-After; falhas transitórias de capacidade usam backoff exponencial limitado com jitter.
• [ ] O polling usa backoff ou é substituído por comportamento de streaming/reconexão.
• [ ] Um teste em etapas abrange qualidade das fontes, latência, custo, comportamento de repetição e alternativas visíveis ao usuário.

Perguntas frequentes sobre a API da Perplexity AI

A API da Perplexity AI é compatível com o SDK da OpenAI?

Sim, mas escolha o formato de API correspondente. A API de Agente usa o formato OpenAI Responses em https://api.perplexity.ai/v1; a API de Orquestrador usa Chat Completions em https://api.perplexity.ai/orchestrator/v1.

Toda solicitação à API de Agente pesquisa a web e inclui citações?

Não. A Perplexity documenta a pesquisa na web como opt-in. Adicione um nível de esforço ou a ferramenta web_search quando precisar de uma saída fundamentada na web; preserve a saída estruturada para que sua aplicação possa renderizar e auditar as citações.

Quanto custa a API da Perplexity AI?

Depende da superfície de API selecionada, do modelo, do uso de tokens, das leituras de cache, dos tokens de raciocínio e das ferramentas. Use a tabela de preços oficial atualizada e meça o uso real das solicitações. Uma solicitação de agente com pesquisa ativada tem componentes de custo tanto de tokens do modelo quanto de ferramentas.

O que devo fazer após um erro de limite de taxa?

Respeite Retry-After, controle o ritmo das novas solicitações e use backoff exponencial limitado com jitter. Não faça polling agressivamente; os polls da API de Agente contam para o limite de solicitações compartilhado da organização.

Próximo passo

Comece com um caso de uso de produção específico: uma resposta de pesquisa com citações, um recurso de pesquisa bruta ou uma chamada de modelo compatível com Chat Completions. Instrumente-o antes de expandir o tráfego. Se o restante da sua aplicação também precisar de modelos compatíveis por trás de um cliente compatível com OpenAI, explore o catálogo de modelos da Flatkey e mantenha explícito o limite do cliente.