Como Formatar a Saída JSON com a API do Perplexity

Quando você usa a API do Perplexity para obter respostas de modelos de linguagem, a resposta bruta é um objeto JSON. Você precisa extrair e formatar esses dados para usar em sua aplicação, dashboard ou arquivo de log. A API retorna dados estruturados que incluem o texto da resposta, citações e estatísticas de uso. Este artigo explica como solicitar a saída JSON da API do Perplexity e como formatar a resposta para legibilidade e processamento adicional.

Entendendo as Respostas JSON da API do Perplexity

A API do Perplexity usa um endpoint de chat completions. Cada requisição inclui uma lista de mensagens e parâmetros opcionais. A resposta é sempre um objeto JSON com campos como id, object, created, model, choices e usage. O array choices contém um ou mais objetos de resposta, cada um com um campo message que contém a resposta do assistente. O objeto message tem um campo content com o texto da resposta. Para obter uma saída JSON estruturada, você deve definir o parâmetro response_format como { "type": "json_object" }. Isso instrui o modelo a retornar sua resposta como uma string JSON válida dentro do campo content. Sem esse parâmetro, o modelo retorna texto simples.

Pré-requisitos para usar a formatação de saída JSON incluem:

• Uma chave de API do Perplexity válida com acesso ao modelo desejado, como sonar-pro ou sonar-small-chat.
• A biblioteca requests em Python ou cliente HTTP equivalente na linguagem de sua escolha.
• Familiaridade com análise JSON básica em seu ambiente de programação.

Passos para Solicitar e Formatar a Saída JSON

Siga estes passos para enviar uma requisição à API do Perplexity e formatar o JSON retornado para legibilidade. Os exemplos usam Python, mas os conceitos se aplicam a qualquer linguagem.

1. Instale a biblioteca requests se ainda não estiver instalada
   Abra seu terminal ou prompt de comando e execute pip install requests. Esta biblioteca gerencia requisições HTTP para a API.
2. Defina sua chave de API e URL do endpoint
   Armazene sua chave de API em uma variável de ambiente ou diretamente em uma variável. O endpoint é https://api.perplexity.ai/chat/completions. Exemplo: api_key = os.getenv('PERPLEXITY_API_KEY') e url = 'https://api.perplexity.ai/chat/completions'.
3. Defina o payload da requisição com response_format
   Crie um dicionário com o nome do modelo, array de mensagens e response_format. Defina "response_format": {"type": "json_object"}. O array de mensagens deve incluir uma mensagem do usuário que instrua o modelo a gerar JSON. Exemplo: {"role": "user", "content": "Liste três linguagens de programação e seus principais casos de uso em formato JSON"}.
4. Envie a requisição POST
   Use requests.post(url, headers=headers, json=payload) onde os headers incluem "Authorization": f"Bearer {api_key}" e "Content-Type": "application/json".
5. Analise o JSON da resposta
   A API retorna um objeto JSON. Chame response.json() para convertê-lo em um dicionário Python. Extraia o conteúdo da mensagem do assistente: content = response.json()['choices'][0]['message']['content']. Este conteúdo é uma string JSON.
6. Analise o JSON do conteúdo e exiba de forma legível
   Use json.loads(content) para converter a string de conteúdo em um dicionário Python. Em seguida, use json.dumps(data, indent=2) para formatá-lo com indentação. Imprima ou registre o resultado.

Exemplo Completo em Python

import requests
import json

api_key = 'sua_chave_api_aqui'
url = 'https://api.perplexity.ai/chat/completions'

payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "user", "content": "Liste três linguagens de programação e seus principais casos de uso em formato JSON"}
    ],
    "response_format": {"type": "json_object"}
}

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

response = requests.post(url, headers=headers, json=payload)
response_data = response.json()
content = response_data['choices'][0]['message']['content']
parsed = json.loads(content)
formatted = json.dumps(parsed, indent=2)
print(formatted)

Erros Comuns e O que Evitar

Esqueceu de definir response_format como json_object

Se você omitir o parâmetro response_format, o modelo retorna texto simples. O campo content conterá uma resposta em linguagem natural, não uma string JSON. Sempre inclua o parâmetro em seu payload.

O modelo retorna JSON inválido no conteúdo

Mesmo com response_format definido, o modelo pode ocasionalmente gerar JSON malformado, especialmente se o prompt for ambíguo. Certifique-se de que sua mensagem do usuário peça explicitamente a saída JSON. Coloque a requisição em um bloco try-except ao chamar json.loads() para lidar com erros de análise graciosamente.

Não extrair a string de conteúdo corretamente

A resposta da API contém a mensagem do assistente em choices[0].message.content. Alguns desenvolvedores tentam analisar toda a resposta da API como o JSON formatado. Lembre-se de que a resposta externa da API é sempre um objeto JSON, mas o conteúdo interno é o JSON que você deseja formatar.

Usar o modelo errado

Nem todos os modelos do Perplexity suportam o parâmetro response_format. Modelos como sonar-small-chat e sonar-pro o suportam. Verifique a documentação mais recente da API para compatibilidade de modelos. Usar um modelo não suportado causa um erro.

Métodos de Saída JSON da API do Perplexity

Item	Resposta Bruta da API	Saída JSON Formatada
Descrição	Objeto JSON completo retornado pelo endpoint da API	Versão com indentação do conteúdo da mensagem do assistente
Estrutura	Contém id, object, created, model, choices, usage	Contém apenas os dados retornados pelo modelo no campo content
Caso de uso	Depuração, registro de metadados completos da requisição	Exibição de respostas, alimentação de sistemas downstream
Método Python	response.json()	json.dumps(json.loads(content), indent=2)

Agora você pode solicitar e formatar a saída JSON da API do Perplexity usando o parâmetro response_format e a biblioteca json do Python. Os passos principais são definir o parâmetro no payload, extrair a string de conteúdo e exibir com indentação usando json.dumps(). Para aplicações em produção, adicione tratamento de erros em torno de json.loads() para capturar respostas malformadas. Você também pode estender o exemplo para escrever o JSON formatado em um arquivo ou passá-lo para um framework web como Flask ou FastAPI.