Como Usar a API do Perplexity para Automação de Pesquisa em Lote

Você precisa coletar grandes volumes de informações de várias fontes sem digitar cada consulta manualmente no navegador. A API do Perplexity permite enviar várias solicitações de pesquisa programaticamente e obter respostas estruturadas. Este artigo explica como configurar a API, escrever scripts em lote e lidar com grandes volumes de dados de pesquisa de forma eficiente.

Entendendo a API do Perplexity para Pesquisa em Lote

A API do Perplexity fornece acesso programático ao mesmo mecanismo de busca e resposta usado na interface web. Você envia uma solicitação contendo uma mensagem do usuário, e a API retorna uma resposta que inclui o texto da resposta, citações e metadados como o modelo usado. Para pesquisa em lote, você envia várias solicitações em sequência, cada uma com uma consulta diferente. A API não impõe um limite rígido de solicitações por dia, mas você deve permanecer dentro dos limites de taxa do seu plano. O plano Pro permite 300 solicitações por dia, enquanto o plano Pro com tokens adicionais suporta volumes maiores. Todas as solicitações usam o método HTTPS POST e esperam payloads no formato JSON.

O que Você Precisa Antes de Começar

Você precisa de uma conta Perplexity Pro, pois a API não está disponível no nível gratuito. Você também precisa de um conhecimento básico de Python ou uma linguagem de script similar. Instale a biblioteca requests para Python. Seu sistema operacional pode ser Windows, macOS ou Linux. Você também precisa de um editor de texto para escrever seu script. A chave da API é uma longa string de letras e números que você gera no site do Perplexity em Account > API Keys. Mantenha essa chave privada. Não a compartilhe nem a envie para repositórios públicos.

Endpoint da API e Formato da Solicitação

A URL do endpoint é https://api.perplexity.ai/chat/completions. O corpo da solicitação deve incluir o parâmetro model, o array messages e, opcionalmente, max_tokens e temperature. O array messages contém pelo menos um objeto com role definido como user e content definido como sua consulta. A resposta retorna um objeto JSON com o array choices, onde cada escolha tem um objeto message contendo a string content e um array citations. Você pode analisar esses campos para extrair a resposta e as URLs das fontes.

Passos para Automatizar Pesquisa em Lote com a API do Perplexity

Siga estes passos para configurar um script Python que lê consultas de um arquivo CSV, envia cada consulta para a API e salva as respostas em um arquivo de texto ou banco de dados.

1. Gere sua chave de API
   Faça login no Perplexity. Clique na sua foto de perfil e selecione Account. Vá para a seção API Keys. Clique em Generate Key. Copie a chave e armazene-a em um local seguro. Você usará essa chave no cabeçalho HTTP Authorization: Bearer SUA_CHAVE_API.
2. Prepare seu arquivo de consultas
   Crie um arquivo CSV chamado queries.csv com uma coluna chamada query. Cada linha contém uma pergunta de pesquisa. Por exemplo: "Quais são as regulamentações de IA mais recentes na UE?". Salve o arquivo na mesma pasta do seu script Python.
3. Escreva o script Python
   Abra seu editor de texto e crie um novo arquivo chamado bulk_research.py. Importe os módulos requests e csv. Defina a URL do endpoint da API e sua chave de API. Use o csv.DictReader para ler cada linha. Dentro de um loop, envie uma solicitação POST com a consulta. Analise a resposta JSON e extraia o texto da resposta e as citações. Escreva o resultado em um novo arquivo nomeado após a consulta ou anexe a um CSV de resultados.
4. Execute o script
   Abra um terminal ou prompt de comando. Navegue até a pasta que contém bulk_research.py. Execute python bulk_research.py. O script enviará cada consulta sequencialmente. Monitore a saída para erros HTTP. Se você atingir o limite de taxa, a API retorna um código de status 429. Adicione uma chamada time.sleep(1) entre as solicitações para permanecer dentro dos limites.
5. Revise os resultados
   Após o script terminar, abra os arquivos de saída. Cada arquivo contém o texto da resposta seguido por uma lista de citações com URLs. Verifique se as respostas são precisas e completas. Se precisar refinar as consultas, edite o arquivo CSV e execute o script novamente.

Exemplo de Código Python

import requests
import csv

API_KEY = "sua-chave-api-aqui"
ENDPOINT = "https://api.perplexity.ai/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

with open("queries.csv", "r") as file:
    reader = csv.DictReader(file)
    for row in reader:
        query = row["query"]
        payload = {
            "model": "sonar-pro",
            "messages": [
                {"role": "user", "content": query}
            ]
        }
        response = requests.post(ENDPOINT, json=payload, headers=headers)
        if response.status_code == 200:
            data = response.json()
            answer = data["choices"][0]["message"]["content"]
            citations = data["citations"]
            with open(f"{query[:30]}.txt", "w") as out:
                out.write(answer + "\n\nFontes:\n")
                for c in citations:
                    out.write(c + "\n")
        else:
            print(f"Erro {response.status_code} para consulta: {query}")

Erros Comuns e Como Evitá-los ao Usar a API

Exceder Limites de Taxa Sem Backoff

Se você enviar solicitações muito rapidamente, a API retorna um erro 429 Too Many Requests. Implemente backoff exponencial capturando o erro e aguardando 5 segundos, depois 10 segundos, depois 20 segundos antes de tentar novamente. Alternativamente, use time.sleep(1) entre as solicitações para ficar abaixo do limite. O plano Pro permite aproximadamente 12 solicitações por minuto. Verifique o limite exato do seu plano na documentação da API.

Armazenar Chaves de API Sensíveis no Código

Codificar sua chave de API no script é um risco de segurança. Use variáveis de ambiente. No Windows, defina PERPLEXITY_API_KEY nas Variáveis de Ambiente do Sistema. Em Python, leia com os.getenv("PERPLEXITY_API_KEY"). Isso evita exposição acidental se você compartilhar seu script no GitHub.

Ignorar Limites de Tokens

Cada resposta da API usa tokens. O modelo sonar-pro suporta até 4096 tokens por resposta. Se sua consulta espera uma resposta muito longa, defina max_tokens para um valor maior, como 2048. Se a resposta for truncada, o campo finish_reason mostrará length. Aumente max_tokens ou divida a consulta em partes menores.

Não Validar a Estrutura da Resposta

A API pode retornar uma mensagem de erro dentro do corpo JSON mesmo com um código de status 200. Sempre verifique o comprimento do array choices e o campo content para valores nulos. Use um bloco try-except para lidar com chaves ausentes. Registre respostas malformadas para revisão manual.

API do Perplexity Gratuita vs Pro: Principais Diferenças para Pesquisa em Lote

Item	Nível Gratuito	Nível Pro
Acesso à API	Não disponível	Incluso
Limite Diário de Solicitações	N/A	300 solicitações por dia
Modelos Disponíveis	N/A	sonar-pro, sonar-reasoning
Limite de Taxa	N/A	12 solicitações por minuto
Máximo de Tokens por Resposta	N/A	4096
URLs de Citação na Resposta	N/A	Inclusas

Agora você pode automatizar pesquisas em lote enviando várias consultas através da API do Perplexity. Comece escrevendo um script Python simples que lê consultas de um arquivo e salva os resultados no disco. Após testar com um pequeno conjunto de consultas, aumente para centenas de perguntas de pesquisa. Para automação avançada, armazene os resultados em um banco de dados SQLite e agende o script com o Agendador de Tarefas do Windows ou cron. Use variáveis de ambiente para sua chave de API para manter suas credenciais seguras.