Como Usar a API do Perplexity com Cliente Node.js

Você quer integrar as capacidades de busca e IA do Perplexity no seu aplicativo Node.js. A API do Perplexity fornece acesso programático aos mesmos modelos de linguagem que alimentam o aplicativo web do Perplexity, permitindo criar ferramentas de busca personalizadas, chatbots e fluxos de automação. Este artigo explica como configurar um cliente Node.js, autenticar suas requisições e enviar consultas para os endpoints da API.

Visão geral da API do Perplexity para Node.js

A API do Perplexity é uma interface RESTful que aceita requisições HTTP e retorna respostas JSON. Ela usa o mesmo formato de chat completion que a OpenAI, tornando-a familiar para desenvolvedores que já trabalharam com APIs similares. O endpoint principal é https://api.perplexity.ai/chat/completions e suporta vários modelos, incluindo sonar-pro, sonar-reasoning-pro e sonar-deep-research.

Antes de enviar requisições, você precisa de uma chave de API válida. Você gera essa chave nas configurações da sua conta Perplexity. A chave deve ser incluída no cabeçalho Authorization de cada requisição. A API atualmente suporta respostas em streaming, prompts de sistema e parâmetros ajustáveis como temperatura e max tokens.

Pré-requisitos

Você precisa do Node.js versão 18 ou superior instalado na sua máquina. Você também precisa de uma assinatura Perplexity Pro ou de um plano apenas de API. A biblioteca axios do Node.js é recomendada para fazer requisições HTTP, mas você também pode usar a API fetch nativa disponível no Node 18+.

Passos para criar um cliente Node.js para a API do Perplexity

1. Obtenha sua chave de API
   Faça login no Perplexity em https://www.perplexity.ai. Navegue até Configurações > API. Clique em “Gerar nova chave” e copie a chave. Armazene-a em uma variável de ambiente chamada PERPLEXITY_API_KEY por segurança.
2. Inicialize seu projeto Node.js
   Execute npm init -y na pasta do seu projeto. Instale o pacote axios executando npm install axios.
3. Crie o arquivo de script principal
   Crie um arquivo chamado perplexity-client.js e abra-o no seu editor.
4. Escreva a função de requisição
   Adicione o seguinte código ao arquivo:

   const axios = require('axios');
   require('dotenv').config();
   
   const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
   
   async function askPerplexity(prompt, model = 'sonar-pro') {
     const response = await axios.post(
       'https://api.perplexity.ai/chat/completions',
       {
         model: model,
         messages: [
           { role: 'system', content: 'Você é um assistente útil.' },
           { role: 'user', content: prompt }
         ],
         max_tokens: 1024,
         temperature: 0.7
       },
       {
         headers: {
           'Authorization': `Bearer ${PERPLEXITY_API_KEY}`,
           'Content-Type': 'application/json'
         }
       }
     );
     return response.data.choices[0].message.content;
   }
   
   module.exports = { askPerplexity };
   

5. Chame a função a partir do seu aplicativo
   Crie um arquivo chamado index.js com o seguinte conteúdo:

   const { askPerplexity } = require('./perplexity-client');
   
   async function main() {
     const answer = await askPerplexity('Quais são os últimos avanços em computação quântica?');
     console.log(answer);
   }
   
   main();
   

6. Execute o script
   Execute node index.js no seu terminal. Você deve ver uma resposta em texto do Perplexity impressa no console.

Lidando com respostas em streaming

Para receber respostas em tempo real conforme os tokens são gerados, defina o parâmetro stream como true no corpo da requisição. A resposta será um fluxo Server-Sent Events (SSE). Use o pacote npm eventsource-parser para analisar o fluxo:

const { createParser } = require('eventsource-parser');

async function askPerplexityStream(prompt) {
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      messages: [{ role: 'user', content: prompt }],
      stream: true
    })
  });

  const parser = createParser((event) => {
    if (event.type === 'event' && event.data !== '[DONE]') {
      const parsed = JSON.parse(event.data);
      const text = parsed.choices[0]?.delta?.content || '';
      process.stdout.write(text);
    }
  });

  for await (const chunk of response.body) {
    parser.feed(new TextDecoder().decode(chunk));
  }
}

Erros comuns e limitações

Chave de API não definida como variável de ambiente

Se você codificar a chave de API diretamente no código-fonte, ela pode ser exposta no controle de versão. Sempre armazene a chave em um arquivo .env e use dotenv para carregá-la. Adicione .env ao seu arquivo .gitignore.

Nome do modelo incorreto causa erro 400

Os nomes dos modelos diferenciam maiúsculas de minúsculas e devem corresponder exatamente às strings listadas na documentação da API do Perplexity. Nomes válidos comuns são sonar-pro, sonar-reasoning-pro e sonar-deep-research. Usar um nome inválido retorna um erro 400 Bad Request.

Limites de taxa excedidos

Contas gratuitas têm um limite de 10 requisições por minuto. Contas Pro permitem até 100 requisições por minuto. Se você exceder o limite, a API retorna um erro 429 Too Many Requests. Implemente backoff exponencial no seu cliente para lidar com isso de forma adequada.

Max tokens muito baixo para respostas longas

Se você definir max_tokens muito baixo, a resposta será cortada. O valor máximo depende do modelo. Para sonar-pro, você pode definir até 4096 tokens. Ajuste este parâmetro com base no comprimento esperado da resposta.

Modelos da API Perplexity: Sonar Pro vs Sonar Reasoning Pro vs Sonar Deep Research

Item	Sonar Pro	Sonar Reasoning Pro	Sonar Deep Research
Velocidade	Rápida	Moderada	Lenta
Max tokens	4096	8192	16384
Melhor para	Perguntas gerais e buscas rápidas	Raciocínio e análise em várias etapas	Pesquisa aprofundada com citações
Custo por requisição	Baixo	Médio	Alto

Você agora configurou um cliente Node.js funcional para a API do Perplexity. Você pode enviar consultas, receber respostas em streaming e lidar com erros comuns. Em seguida, explore o modelo sonar-deep-research para tarefas que exigem citações detalhadas e saídas estruturadas. Para uso avançado, considere adicionar uma camada de cache com Redis para reduzir custos de API para perguntas repetidas.