Modo JSON da API Perplexity Retorna Markdown: Correção

Quando você usa o modo JSON da API Perplexity, espera uma saída JSON estruturada. Em vez disso, a API às vezes retorna texto markdown envolto em três crases. Isso quebra a lógica da sua aplicação e exige análise extra. A causa raiz é uma incompatibilidade entre o endpoint da API e o modelo usado. Este artigo explica por que o modo JSON retorna markdown e fornece uma correção passo a passo para obter uma saída JSON limpa.

Por que o Modo JSON da API Perplexity Retorna Markdown

A API Perplexity oferece um modo JSON que deve retornar JSON estruturado. Quando você define response_format: { "type": "json_object" }, a API deve forçar a saída JSON. No entanto, o modelo de linguagem subjacente pode ainda gerar cercas de código markdown ao redor do JSON. Isso geralmente acontece com modelos não otimizados para o modo JSON ou quando o prompt do sistema não possui instruções explícitas para apenas JSON.

A causa técnica é que o modelo trata o modo JSON como uma sugestão, não como uma regra estrita. Alguns modelos mais antigos, como sonar-small-online ou sonar-medium-chat, não cumprem totalmente o parâmetro response_format. O modelo pode envolver o JSON em três crases porque aprendeu isso a partir dos dados de treinamento. A correção requer o uso de um modelo compatível e o reforço do comportamento apenas JSON por meio do prompt do sistema.

Passos para Forçar Saída JSON Limpa

1. Use um modelo compatível
   Defina o parâmetro model como sonar-pro ou sonar-medium-online. Esses modelos foram testados e retornam JSON bruto quando response_format está definido. Evite sonar-small-online e sonar-medium-chat para o modo JSON.
2. Defina o parâmetro response_format
   Inclua "response_format": { "type": "json_object" } no corpo da sua requisição à API. Isso informa à API que você espera um objeto JSON e instrui o modelo de acordo.
3. Adicione uma mensagem de sistema com instruções JSON estritas
   Inclua uma mensagem de sistema que diga: "Você é um assistente que gera apenas JSON. Gere apenas JSON válido. Não use cercas de código markdown ou qualquer outra formatação." Isso reforça o comportamento.
4. Envie uma mensagem de usuário que solicite JSON
   Na mensagem do usuário, peça explicitamente JSON. Exemplo: "Retorne os seguintes dados como um objeto JSON com as chaves 'nome', 'idade', 'cidade'. Nenhum outro texto."
5. Analise a resposta no seu código
   Mesmo com todas as precauções, alguns modelos ainda podem retornar markdown. No código da sua aplicação, remova as três crases e a palavra “json” antes de analisar. Use uma regex como /```json?\n?/g para remover as cercas.
6. Teste com uma requisição mínima
   Envie uma requisição simples para verificar JSON limpo. Exemplo de comando curl:
   curl -X POST https://api.perplexity.ai/chat/completions -H "Authorization: Bearer SUA_CHAVE_API" -H "Content-Type: application/json" -d '{"model":"sonar-pro","messages":[{"role":"system","content":"Gere apenas JSON válido, sem markdown"},{"role":"user","content":"Retorne um objeto JSON com a chave 'teste' e o valor 'sucesso'"}],"response_format":{"type":"json_object"}}'

Se a API Perplexity Ainda Retornar Markdown Após a Correção

“A API retorna markdown mesmo com sonar-pro”

Se você ainda vir três crases, verifique sua mensagem de sistema. Alguns modelos ignoram uma instrução única. Adicione uma segunda mensagem de sistema ou inclua a instrução também na mensagem do usuário. Verifique também se sua requisição à API usa o endpoint correto /chat/completions, não o endpoint legado /completions.

“O modo JSON não funciona para respostas em streaming”

Respostas em streaming podem retornar markdown mesmo quando requisições não streaming funcionam. Para streaming, o modelo pode gerar tokens parciais que incluem crases. Considere usar requisições não streaming para o modo JSON. Se você precisar usar streaming, acumule a resposta completa e depois remova o markdown no seu código.

“A API retorna um erro quando defino response_format”

Alguns modelos não suportam o parâmetro response_format. Consulte a documentação da API Perplexity para a lista de modelos compatíveis. Em 2025, sonar-pro e sonar-medium-online o suportam. Modelos mais antigos, como sonar-small-chat, retornarão um erro. Mude para um modelo compatível.

Item	Modelo com Suporte ao Modo JSON	Modelo sem Suporte ao Modo JSON
Nome do Modelo	sonar-pro, sonar-medium-online	sonar-small-online, sonar-medium-chat
Comportamento do Modo JSON	Retorna JSON bruto quando response_format está definido	Pode retornar markdown ou ignorar response_format
Uso Recomendado	Todas as requisições em modo JSON	Chat geral, não modo JSON
Tratamento de Erros	Nenhum erro com response_format	Pode retornar erro ou recorrer a markdown

Agora você pode corrigir o problema do modo JSON da API Perplexity mudando para um modelo compatível, definindo o parâmetro response_format e adicionando instruções JSON estritas à mensagem de sistema. Se os problemas persistirem, remova o markdown no seu código com uma regex. Para aplicações em produção, sempre valide a saída JSON com um analisador JSON e registre quaisquer falhas de análise para depuração.