Tutorial da API Perplexity: Como criar uma resposta com aterramento na fonte, passo a passo

API PERPLEXITY · TUTORIAL EM PYTHON · 2026

Este tutorial da API Perplexity mostra como criar um script em Python que retorne uma resposta com fontes da web clicáveis. Use a API do Agente para enviar uma pergunta, ler a resposta, associar seus marcadores de citação aos IDs das fontes e exportar um arquivo Markdown para que você possa revisá-lo.

Vamos usar uma pergunta ao longo de todo o texto: Como um pequeno projeto em Python deve utilizar ambientes virtuais e gerenciar dependências? Comece com uma solicitação básica e, em seguida, adicione a análise da fonte e os filtros de domínio. É necessário ter conhecimentos básicos de Python e uma conta de desenvolvedor Perplexity com o faturamento da API configurado.

Se você também usa IA para pesquisas e redação no dia a dia, Perplexity em GlobalGPT oferece acesso em um ambiente de trabalho de IA completo, reduzindo a necessidade de alternar entre ferramentas distintas. Esse fluxo de trabalho do consumidor é independente da chave do desenvolvedor e do faturamento da API utilizados aqui.

Resposta rápida: Use o rápido Predefinição do agente para uma primeira resposta baseada na web, leia response.output_text para saber a resposta e ler o resultados_da_busca item em response.output para fontes. Associe cada marcador embutido a uma fonte por meio do valor retornado id. Uma citação significa que “a resposta aponta para esse resultado”; ela não garante que a página comprove todas as afirmações.

Exemplo de status: A sintaxe da solicitação segue a documentação oficial verificada em 28 de setembro de 2026. O auxiliar de citação foi testado com dados de amostra offline; nenhuma solicitação paga à API foi realizada para este tutorial. Os registros de origem mostrados na ilustração são exemplos ilustrativos.

• Qual API Perplexity você deve usar?
• Passo 1: Obter uma chave de API e configurar o Python
• Etapa 2: Envie sua primeira solicitação com aterramento na fonte
• Etapa 3: Extraia a resposta e identifique suas fontes
• Etapa 4: Aprimore a resposta com filtros de busca
• Etapa 5: Salve uma resposta completa com fontes clicáveis
• Transmissão contínua e saída estruturada
• Custos e erros comuns
• Mudando de um tutorial mais antigo do Sonar
• Perguntas frequentes

Tutorial da API Perplexity: escolha a API certa

Essas são interfaces para desenvolvedores. O produto de chat pode oferecer funcionalidades semelhantes de maneira diferente; nossa visão geral sobre Recursos do Perplexity descreve a experiência do usuário.

Da Perplexity’s Guia rápido da API oficial agrupa seus produtos para desenvolvedores de acordo com a tarefa que você precisa realizar. Escolha a menor área possível que gere os dados de que seu aplicativo realmente precisa.

Este tutorial escolhe o Agent porque o resultado desejado é uma resposta completa, acompanhada de suas fontes. Para conhecer o fluxo de trabalho de pesquisa de forma mais ampla, consulte nosso guia sobre utilização do Perplexity para pesquisa.

Sobre o Sonar: A corrente visão geral da migração afirma que o Sonar Chat Completions continua sendo suportado e recomenda o Agent para todos os novos projetos. Portanto, este tutorial utiliza o Agent. Não se deve deduzir que uma integração antiga tenha deixado de funcionar com base em um prazo mencionado em um tutorial mais antigo.

Passo 1: Obter uma chave de API e configurar o Python

Criar a chave e preparar o faturamento

Abra o console da API Perplexity, escolha ou crie o projeto que você vai usar, configure o faturamento da API e crie uma chave. Mantenha-a no lado do servidor. As APIs para desenvolvedores são cobradas separadamente das assinaturas de consumidores; verifique o saldo do seu projeto antes de fazer solicitações.

Instale o SDK oficial

python -m venv .venv

# macOS/Linux: escolha este comando de ativação
source .venv/bin/activate

# Windows PowerShell: use este comando em vez disso
.venv\Scripts\Activate.ps1

python -m pip install --upgrade perplexityai

Use o Python 3.10 ou uma versão mais recente para o código abaixo. Ative o ambiente usando o comando correspondente ao seu sistema operacional e, em seguida, instale o SDK. Se o PowerShell bloquear a ativação, use .venv\Scripts\python.exe em vez de Python para instalação e execução de scripts.

O nome do pacote é perplexityai, enquanto a importação do Python é perplexidade. Use um ambiente virtual para que as dependências deste tutorial não alterem outro projeto.

O exemplo utiliza uma questão relacionada à programação porque suas afirmações podem ser verificadas com base na documentação atualizada. Nosso guia para Perplexity para codificação explica como o apoio à pesquisa se encaixa no contexto de testar o código por conta própria.

Defina a chave da API como uma variável de ambiente

# macOS/Linux
export PERPLEXITY_API_KEY="sua-chave-aqui"

# Windows PowerShell
$env:PERPLEXITY_API_KEY = "sua-chave-aqui"

O SDK lê PERPLEXIDADE_CHAVE_API ao criar o cliente. Não cole a chave em um bloco de notas, não a envie para o Git nem a envie para um navegador. Se você usar um arquivo .env localmente, mantenha esse arquivo fora do controle de versão e carregue-o com a biblioteca de variáveis de ambiente de sua escolha.

Etapa 2: Envie sua primeira solicitação com aterramento na fonte

Guia rápido da API do Agent documentos POST https://api.perplexity.ai/v1/agent. Seu cliente em Python encapsula a solicitação com client.responses.create(). O rápido A configuração padrão habilita a pesquisa na web, o que mantém o primeiro exemplo conciso.

from perplexity import Perplexity

client = Perplexity()

question = (
    "Como um pequeno projeto em Python deve usar ambientes virtuais "
    "e gerenciar dependências?"
)

resposta = cliente.respostas.criar(
    predefinição="rápido",
    entrada=pergunta,
)

print(resposta.texto_de_saída)

Salve o trecho como first_request.py, em seguida, execute python first_request.py no mesmo terminal em que você definiu a chave. Uma chamada bem-sucedida deve exibir um texto de resposta que não esteja vazio. Se você precisar de comprovação do resultado, prossiga para a etapa de extração da fonte; o texto por si só não constitui uma verificação completa.

A propriedade de conveniência texto_de_saída fornece o texto da resposta final. Guarde também o objeto de resposta completo: os registros de origem e os detalhes de uso estão na saída digitada, e não apenas no parágrafo impresso.

A mesma solicitação com o cURL

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "fast",
    "input": "Como um pequeno projeto em Python deve usar ambientes virtuais e gerenciar dependências?"
  }'

Este exemplo do cURL utiliza a sintaxe do Bash para macOS/Linux ou um shell compatível com o Bash. Cada execução gera uma nova solicitação cobrável. Utilize-o apenas quando for necessário isolar um problema no endpoint de um problema no Python; não execute todas as versões apenas para acompanhar o exemplo.

Equivalente em JavaScript do lado do servidor

O Node.js 18+ inclui buscar, portanto, um teste de funcionamento do lado do servidor não requer nenhuma biblioteca adicional. Leia o código-fonte saída itens na resposta JSON; o SDK do Python oferece a conveniente texto_de_saída acessório.

const res = await fetch("https://api.perplexity.ai/v1/agent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    preset: "fast",
    input: "Como um pequeno projeto em Python deve usar ambientes virtuais e gerenciar dependências?"
  })
});
if (!res.ok) throw new Error(`Perplexity HTTP ${res.status}`);
console.log(await res.json());

Etapa 3: Extraia a resposta e identifique suas fontes

O guia oficial de citações distingue a prosa de seus registros de evidências. As fontes chegam em um saída item do tipo resultados_da_busca. Leia o artigo sobre esse assunto resultados e associar cada marcador de citação ao resultado id. Um resultado possui um título e uma URL; trate os valores ausentes antes de exibi-lo.

Esse último detalhe é importante. Não presuma que a “citação 1” seja sempre o primeiro elemento de uma matriz depois que outra ferramenta adiciona um item. Crie uma consulta por ID e, em seguida, identifique os marcadores que realmente aparecem na resposta.

def field(obj, name, default=None):
    return obj.get(name, default) se isinstance(obj, dict), caso contrário, getattr(obj, name, default)

def source_index(output):
    sources = {}
    for item in output or []:
    if field(item, "type") != "search_results":
        continue
    for result in field(item, "results", []) or []:
            sid, url = field(result, "id"), field(result, "url")
 se sid for None:
 continue
 key = str(sid)
 se key estiver em sources e field(sources[key], "url") != url:
                raise ValueError(f"URLs conflitantes para o ID de fonte {key}")
 sources[key] = result
    return sources

sources = source_index(response.output)
print(sources.get("7"))  # Um ID de fonte, não a posição 7 da matriz

O script completo abaixo reconhece [1] e [web:1], os formatos de citação documentados para as predefinições comuns. O auxiliar acima lida tanto com objetos do SDK quanto com dicionários e rejeita URLs conflitantes atribuídas ao mesmo ID. Ele não renumera os resultados nem tenta adivinhar uma fonte ausente.

Para uma discussão mais ampla sobre a qualidade das citações, consulte nosso Guia de precisão de citações do Perplexity. Uma citação é um registro de auditoria; seu aplicativo ainda precisa de uma política para páginas desatualizadas, URLs duplicadas e alegações sem fundamento.

Por exemplo, se o array retornado contiver o ID 2 seguido pelo ID 7, o marcador [7] deve estar vinculado ao ID 7. Se a mesma URL aparecer nos IDs 7 e 9, você pode exibi-la uma vez, mantendo ambos os IDs. Se o ID 8 nunca for recebido, mantenha [8] visível e marcá-lo como sem correspondência.

Etapa 4: Aprimore a resposta com filtros de busca

Assim que a consulta básica funcionar, restrinja a pesquisa quando sua dúvida tiver um escopo de referência bem definido. Para o gerenciamento de pacotes em Python, a documentação da linguagem e o guia de gerenciamento de pacotes são pontos de partida melhores do que um tutorial qualquer.

response = client.responses.create(
    preset="fast",
    input=(
 "Como um pequeno projeto em Python deve utilizar ambientes virtuais "
 "e gerenciar dependências? Cite as orientações que você utiliza."
    ),
    ferramentas=[
 {
 "tipo": "pesquisa_na_web",
 "filtros": {
 "filtro_de_domínio_de_pesquisa": [
 "docs.python.org",
                    "packaging.python.org",
 ]
 },
 }
    ],
)

O filtro deve ser configurado na ferramenta de pesquisa na web. A documentação de migração também descreve filtro_de_recência_da_busca para perguntas que exigem respostas rápidas. Utilize a atualidade quando a pergunta depender de lançamentos ou notícias recentes; uma combinação muito restrita de domínio e data pode resultar em poucas evidências.

Para uma pergunta sobre lançamentos do mês passado, adicione "search_recency_filter": "mês" ao lado de filtro_de_domínio_de_busca. Não inclua isso no exemplo do ambiente virtual: a documentação estável pode ter uma data de publicação mais antiga. Se você mudar de um modelo predefinido para um modelo selecionado diretamente, inclua explicitamente a ferramenta de busca na web.

Compare os resultados filtrados e não filtrados durante o desenvolvimento. Se a resposta mudar, registre o motivo: um filtro pode remover contexto útil ou páginas de baixa autoridade que estavam confundindo o modelo. Trata-se de uma decisão de qualidade, não de uma garantia de que todas as páginas restantes estejam corretas.

Se seu aplicativo precisar apenas de links classificados e trechos, chame a função API de pesquisa e faça você mesmo a síntese. Essa separação pode facilitar a revisão e o armazenamento em cache. Para uma comparação mais ampla com o Google, consulte em que o Perplexity difere do Google.

Etapa 5: Salve uma resposta completa com fontes clicáveis

Salve o seguinte como perplexity_tutorial.py. É um sistema autônomo: inclui o auxiliar de fonte, aplica o filtro de domínio da documentação do Python, transforma marcadores de citação correspondentes em links, agrupa URLs duplicadas sem perder os IDs e salva a resposta completa do SDK junto com o Markdown.

from pathlib import Path
from collections import defaultdict
from urllib.parse import urlsplit
import json
import re

QUESTION = (
 "Como um pequeno projeto em Python deve usar ambientes virtuais "
 "e gerenciar dependências?"
)
# Suporta os formatos documentados [1] e [web:1] em respostas em prosa.
CITATION_RE = re.compile(r"(?<!!)\[(?:web:)?(\d+)\](?!\()")

def field(obj, name, default=None):
 return obj.get(name, default) if isinstance(obj, dict) else getattr(obj, name, default)

def source_index(output):
 sources = {}
 for item in output or []:
 if field(item, "type") != "search_results":
 continue
 for result in field(item, "results", []) or []:
 sid, url = field(result, "id"), field(result, "url")
 se sid for None:
 continue
 key = str(sid)
 se key estiver em sources e field(sources[key], "url") != url:
 raise ValueError(f"URLs conflitantes para o ID de fonte {key}")
 sources[key] = result
 return sources

def safe_url(value):
 if not isinstance(value, str):
 return None
 parsed = urlsplit(value)
 se parsed.scheme não estiver em ("http", "https") ou não for parsed.netloc:
 return None
 # Proteger um destino entre colchetes angulares no Markdown.
 return value.replace("", "").replace(" ", "")

def md_label(valor):
 return re.sub(r"([\\\[\]])", r"\\\1", str(valor).replace("\n", " "))

def export_markdown(resposta, saída, pergunta=PERGUNTA):
 fontes = source_index(saída)
 citadas = list(dict.fromkeys(CITATION_RE.findall(resposta)))
 missing = [
 sid for sid in cited
 if sid not in sources or not safe_url(field(sources[sid], "url"))
 ]
 def link(match):
 sid = match.group(1)
 url = safe_url(field(sources.get(sid, {}), "url"))
 return f"[{match.group(0)[1:-1]}]()" se url for válido, caso contrário, retorne match.group(0)

 # Manter todos os IDs quando a mesma URL aparecer sob IDs diferentes.
 grouped = defaultdict(list)
 titles = {}
 for sid in cited:
 source = sources.get(sid, {})
 url = safe_url(field(source, "url"))
 if url:
 grouped[url].append(sid)
 titles.setdefault(url, field(source, "title") or url)

 lines = ["# Resposta fundamentada na fonte", "", question, "",
 CITATION_RE.sub(link, answer), "", "## Fontes citadas", ""]
 para url, ids em grouped.items():
 lines.append(f"- IDs {', '.join(ids)}: [{md_label(titles[url])}]()")
 se houver ausências:
 lines.append("- IDs de fontes não correspondentes ou inutilizáveis: " + ", ".join(ausências))
 se não houver citação:
 lines.append("- Nenhuma citação embutida reconhecida; evidência não verificada.")
 lines.extend(["", "Os links de origem precisam ser revisados; a correspondência de IDs não confirma as alegações."])
 return "\n".join(lines) + "\n"

def main():
 from perplexity import Perplexity
 response = Perplexity().responses.create(
 preset="fast",
 input=QUESTION,
 tools=[{"type": "web_search", "filters": {
 "search_domain_filter": ["docs.python.org", "packaging.python.org"]
 }}],
 )
 resposta = response.output_text or ""
 if not resposta.strip():
 raise RuntimeError("Nenhum texto de resposta foi retornado; verifique o status da resposta e os erros.")
 Path("perplexity-response.json").write_text(
 response.model_dump_json(indent=2), encoding="utf-8"
 )
 Path("perplexity-answer.md").write_text(
 export_markdown(answer, response.output), encoding="utf-8"
 )
 print("Arquivos perplexity-answer.md e perplexity-response.json salvos")

if __name__ == "__main__":
 main()

Executar python perplexity_tutorial.py a partir do diretório do seu projeto. Ele grava perplexity-answer.md e perplexity-response.json ali, substituindo os arquivos anteriores com esses nomes. O arquivo Markdown contém a pergunta, a resposta com link, as fontes citadas e quaisquer IDs sem correspondência. O arquivo JSON mantém a saída retornada e as informações de uso para fins de diagnóstico.

O analisador tem como alvo as formas documentadas de marcador único na prosa. Não se trata de um analisador completo de Markdown: se o seu aplicativo solicitar Markdown arbitrário, exemplos de código ou citações como, por exemplo, [1,2], adicione um renderizador com reconhecimento de sintaxe e testes para esse formato. Não reinterprete silenciosamente marcadores desconhecidos.

Verifique se a página vinculada confirma a resposta

Nesse exemplo, verifique se a documentação citada realmente explica o isolamento de ambiente e a instalação de dependências. Um link para a página inicial do Python é menos útil do que a seção relevante da documentação. Se uma resposta recomendar um comando específico, verifique o sistema operacional e a versão do Python antes de executá-lo. Mark alega que o texto citado não justifica a classificação como “não resolvido”.

Adicione saída contínua ou estruturada quando necessário

Transmissão

O streaming melhora a latência percebida em uma interface de chat. O guia de migração do Agente documenta eventos de delta de texto, tais como response.output_text.delta. Exiba essas atualizações à medida que forem chegando, mas colete também os itens da resposta final para que sua interface de usuário possa mostrar as fontes assim que a resposta for concluída. Um fluxo de texto por si só não constitui uma lista de fontes.

O texto a seguir é apenas para exibição. Mantenha a exportação sem streaming para o seu primeiro registro de origem completo; uma implementação de streaming em produção também deve coletar os eventos de ferramenta/saída e lidar com execuções interrompidas ou com falha.

stream = client.responses.create(
    preset="fast", input=question, stream=True
)
for event in stream:
    if event.type == "response.output_text.delta":
 print(event.delta, end="", flush=True)

Saída estruturada

Utilize uma resposta estruturada quando o código posterior precisar de campos como resposta, nota de confiança e perguntas_de_aprofundamento. Mantenha os IDs de origem em um campo separado ou preserve a saída original do Agent para que seu esquema não oculte as evidências. Valide o esquema em seus próprios casos de teste antes de utilizá-lo em um fluxo de trabalho.

A referência de migração mantém formato_da_resposta com tipo: "json_schema" para saída estruturada. Defina os campos obrigatórios e desative propriedades inesperadas quando for o caso. As verificações de validade do esquema se referem à forma, não à veracidade: os IDs de origem ainda precisam corresponder aos registros efetivamente retornados, e um rótulo de confiança gerado pelo modelo não constitui uma medida de precisão.

Custos e erros comuns da API Perplexity

Página oficial de preços do Perplexity, consultado em 28 de setembro de 2026, separa os tokens do modelo do Agente das chamadas de ferramentas. A seguir estão as tarifas em USD referentes às ferramentas e às pesquisas. O rápido Predefinição do agente e search_type: "rápido" são opções de configuração diferentes; não se deve inferir a taxa de busca a partir do nome da predefinição.

Exemplo: O custo de 1.000 chamadas padrão de pesquisa na web mais 1.000 acessos a URLs $3.00 em custos de ferramentas ($2.50 + $0.50), antes dos tokens de modelo ou de outros encargos. Trata-se de uma estimativa de carga de trabalho, não de um custo medido para o tutorial. Uma única solicitação do Agente pode acionar várias ferramentas. Quando disponível, verifique uso.custo.custo_total na resposta preenchida.

A API de pesquisa cobra pelas solicitações bem-sucedidas, incluindo aquelas que não retornam resultados; o preço da solicitação não inclui cobrança adicional por tokens. Os custos do agente dependem dos tokens do modelo e das ferramentas. Mantenha essas unidades de cobrança separadas ao comparar um fluxo de trabalho com respostas com um fluxo de trabalho apenas de pesquisa.

Para uma comparação de orçamentos de API, nosso Guia de custos da API Perplexity fornece informações adicionais, embora a página oficial de preços continue sendo a fonte oficial para as tarifas atuais.

Mudando de um tutorial mais antigo do Sonar

Muitos resultados de pesquisa ainda exibem o formato antigo do “Chat Completions”. O guia de migração do Agente utiliza um mapeamento conceitual direto. Se você estiver comparando os rótulos do modelo de consumidor com as predefinições da API, consulte nosso guia explicativo sobre o que o LLM Perplexity usa fornece contexto, mas não substitui a documentação da API do Agente.

Leia a cobertura ao vivo visão geral da migração e detalhes da migração antes de alterar o código de produção. Os mapeamentos predefinidos são um ponto de partida, não uma garantia de que os modelos antigos e novos produzam qualidade, latência ou custo idênticos.

Perguntas frequentes

A API Perplexity é gratuita?

As APIs são cobradas por uso, conforme o guia rápido e a documentação de preços atuais. Não presuma que uma assinatura de consumidor, um período de teste ou um crédito promocional tornem todas as solicitações de API gratuitas.

Preciso do Perplexity Pro para usar a API?

O acesso à API e o plano Pro para consumidores são produtos distintos. Crie credenciais de API e verifique o faturamento da API para a conta de desenvolvedor que você pretende usar.

Devo usar a API do Agent ou a API de Pesquisa?

Escolha “Agente” quando desejar uma resposta completa e fundamentada, com fontes. Escolha “Pesquisa” quando seu aplicativo precisar realizar classificação, filtragem e síntese. Você pode combinar a “Pesquisa” com seu próprio modelo caso precise de controle rigoroso sobre cada etapa de geração.

Posso chamar o Perplexity a partir do JavaScript?

Sim. Use o exemplo do Node.js do lado do servidor apresentado acima ou o SDK oficial do JavaScript. Mantenha a chave no servidor. Ao ler JSON bruto, analise os itens de saída tipados e aplique as mesmas regras de mapeamento de ID de origem.

As citações do Perplexity têm garantia de que estão corretas?

Não. Uma referência indica a qual resultado retornado a resposta se refere. Seu aplicativo ou revisor ainda deve verificar a atualidade, a autoridade e se a página corrobora a afirmação exata.

Por que meu analisador não encontrou nenhuma fonte?

Inspecione os tipos de itens da saída bruta, confirme se a pesquisa na web foi executada e verifique se sua expressão regular corresponde ao formato de citação da predefinição. Se nenhum marcador aparecer, salve a resposta como “não verificada” e investigue a solicitação, em vez de adicionar um link baseado em suposições.

A chave API GlobalGPT pode substituir uma chave API Perplexity?

O GlobalGPT é um espaço de trabalho de IA completo para o uso diário da IA. Sua assinatura e o acesso aos modelos são independentes da conta de desenvolvedor do Perplexity, da chave de API e dos créditos de API; este tutorial em Python utiliza a conta de desenvolvedor.

Uma lista de verificação prática para o lançamento

• Crie uma chave do lado do servidor e confirme o faturamento da API.
• Execute o mínimo rápido solicitação antes de adicionar filtros ou iniciar a transmissão.
• Salve a resposta completa, e não apenas o texto visível da resposta.
• Correlacionar os marcadores de citação com os IDs das fontes retornadas e sinalizar os marcadores que não tiverem correspondência.
• Analise as páginas citadas quanto ao fundamento das alegações, atualidade e URLs duplicados.
• Verifique novamente a documentação sobre o Live Agent, preços e migração antes da implantação.

Agora você já conhece o padrão básico para uma integração confiável da API Perplexity: faça uma pergunta específica, deixe que a API do Agente faça a busca, mantenha a resposta e as evidências juntas e torne cada citação auditável. A partir daí, adicione cache, tentativas de repetição e suas próprias regras de revisão em torno do mesmo fluxo de trabalho de ID de fonte.