DeepSeek JSON Output: guia completo para gerar JSON válido na API

DeepSeek JSON Output é o modo da DeepSeek API para retornar respostas em formato JSON válido, útil quando você precisa de saída estruturada para automações, integrações, extração de dados e pipelines. Ele é ativado com response_format: {"type":"json_object"} nas chamadas de Chat Completions. Mesmo assim, você ainda precisa escrever um prompt claro, incluir a palavra json, definir max_tokens suficiente, fazer parsing de message.content e validar os dados no backend. A própria documentação da DeepSeek recomenda usar response_format, pedir JSON explicitamente no prompt, fornecer um exemplo do formato esperado e evitar truncamento com max_tokens adequado.

TL;DR

• Use response_format: {"type":"json_object"} para ativar o DeepSeek JSON Output.
• Inclua a palavra json no system ou no user prompt.
• Dê um exemplo explícito do objeto JSON esperado.
• Leia a resposta final em response.choices[0].message.content.
• Verifique finish_reason; se for "length", o JSON pode ter sido cortado.
• Faça json.loads em Python ou JSON.parse em TypeScript/Node.js.
• Valide o schema no backend com Pydantic, Zod ou outra biblioteca.
• Use Tool Calls quando o modelo precisar solicitar a execução de uma função externa.

O que é DeepSeek JSON Output?

DeepSeek JSON Output é um recurso da DeepSeek API que orienta o modelo a gerar a resposta em formato JSON, em vez de texto livre. Em uma resposta comum, o modelo pode retornar frases, listas, Markdown, explicações e observações adicionais. Isso é útil para chat, mas ruim para sistemas que precisam consumir a saída automaticamente.

Com JSON Output, o objetivo é receber algo como:

{
  "categoria": "financeiro",
  "prioridade": "alta",
  "resumo": "Cliente relata cobrança duplicada.",
  "acao_recomendada": "Abrir chamado para revisão de faturamento."
}

Essa estrutura é muito mais fácil de conectar a um CRM, banco de dados, dashboard, sistema de tickets, ferramenta de ETL ou workflow de automação. Em chamadas não stream, a saída final costuma ser lida em message.content; a referência de Chat Completion da DeepSeek mostra message.content como o conteúdo da mensagem gerada pelo modelo, enquanto reasoning_content aparece separadamente quando o Thinking Mode está em uso.

O ponto mais importante: JSON válido não significa schema correto. O DeepSeek JSON mode ajuda a obter uma resposta parseável como JSON, mas não substitui validação de campos, tipos, enums, limites, datas, permissões ou regras de negócio.

Casos comuns de uso incluem:

• extração de dados de e-mails, tickets e documentos;
• classificação de solicitações de suporte;
• automação de CRM;
• geração de metadados SEO;
• normalização de produtos para catálogo;
• resumos estruturados;
• pipelines internos que dependem de objetos previsíveis.

Como ativar DeepSeek JSON Output na API

Para ativar DeepSeek JSON Output, use a API de Chat Completions e envie response_format com type igual a json_object. A documentação da DeepSeek informa que os valores possíveis para response_format.type são text e json_object; também alerta que, sem uma instrução explícita para produzir JSON, a resposta pode gerar um fluxo de espaços em branco até atingir o limite de tokens.

Fluxo recomendado:

1. Use o endpoint de Chat Completions.
2. Escolha deepseek-v4-flash ou deepseek-v4-pro.
3. Defina response_format: {"type":"json_object"}.
4. Inclua a palavra json no system ou no user prompt.
5. Mostre o formato JSON esperado.
6. Configure max_tokens com folga.
7. Leia message.content.
8. Faça parsing.
9. Valide o schema no backend.
10. Trate erro, truncamento, campos ausentes e saída vazia.

Checklist rápido:

• O prompt contém a palavra json?
• O prompt pede “somente JSON, sem Markdown”?
• O objeto raiz está claro?
• Campos obrigatórios foram listados?
• Enums foram definidos?
• Valores desconhecidos usam null ou uma string padronizada?
• max_tokens é suficiente?
• O backend verifica finish_reason?
• O backend valida tipos e regras de negócio?

Exemplo rápido com cURL

O exemplo abaixo classifica um ticket de suporte. Ele pede um objeto JSON, bloqueia Markdown e define campos obrigatórios.

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "Você é um classificador de tickets. Responda somente em json válido. Não use Markdown, não use code fences e não escreva texto antes ou depois do objeto JSON."
      },
      {
        "role": "user",
        "content": "Classifique este ticket de suporte e retorne json no formato: {\"categoria\":\"billing|technical|account|other\", \"prioridade\":\"baixa|media|alta|critica\", \"resumo\":\"string\", \"sentimento\":\"positivo|neutro|negativo\", \"precisa_humano\":true}. Ticket: Cliente diz que foi cobrado duas vezes no cartão e precisa de reembolso urgente."
      }
    ],
    "response_format": {
      "type": "json_object"
    },
    "max_tokens": 600,
    "thinking": {
      "type": "disabled"
    },
    "stream": false
  }'

Resposta esperada:

{
  "categoria": "billing",
  "prioridade": "alta",
  "resumo": "Cliente relata cobrança duplicada no cartão e solicita reembolso urgente.",
  "sentimento": "negativo",
  "precisa_humano": true
}

Use deepseek-v4-flash quando o trabalho for rápido, repetitivo e de alto volume. Para documentos longos, decisões mais complexas ou revisão de código, considere deepseek-v4-pro.

Exemplo em Python com OpenAI SDK

A DeepSeek API é compatível com o formato OpenAI/Anthropic, e a documentação oficial mostra o uso do OpenAI SDK com base_url="https://api.deepseek.com" e modelos como deepseek-v4-pro ou deepseek-v4-flash.

import json
import os
from json import JSONDecodeError
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com",
)

system_prompt = """
Você é um classificador de tickets.
Responda somente em json válido.
Não use Markdown, não use ``` e não escreva texto antes ou depois do JSON.

Formato obrigatório:
{
  "categoria": "billing|technical|account|other",
  "prioridade": "baixa|media|alta|critica",
  "resumo": "string",
  "sentimento": "positivo|neutro|negativo",
  "precisa_humano": true
}

Se não souber algum valor, use null quando o campo permitir.
"""

user_prompt = """
Classifique este ticket:

"Não consigo acessar minha conta desde ontem. Já redefini a senha,
mas o login continua falhando. Preciso resolver hoje."
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ],
    response_format={"type": "json_object"},
    max_tokens=700,
    stream=False,
    extra_body={"thinking": {"type": "disabled"}},
)

choice = response.choices[0]

if choice.finish_reason == "length":
    raise RuntimeError(
        "A resposta foi truncada. Aumente max_tokens ou reduza o prompt."
    )

content = choice.message.content or ""

if not content.strip():
    raise RuntimeError("A API retornou empty content. Ajuste o prompt e tente novamente.")

try:
    data = json.loads(content)
except JSONDecodeError as exc:
    raise RuntimeError(f"Falha ao fazer parsing do JSON: {exc}") from exc

print(data)

Esse código cobre três falhas frequentes: truncamento por finish_reason="length", empty content e erro de parsing com json.loads.

Exemplo em TypeScript/Node.js com JSON.parse

Em Node.js, o fluxo é o mesmo: chamar a DeepSeek API com OpenAI SDK, ativar response_format, ler message.content, fazer JSON.parse e validar. Segundo a MDN, JSON.parse() transforma uma string JSON em um valor ou objeto JavaScript e lança SyntaxError quando a string não é JSON válido.

import OpenAI from "openai";

type TicketOutput = {
  categoria: "billing" | "technical" | "account" | "other";
  prioridade: "baixa" | "media" | "alta" | "critica";
  resumo: string;
  sentimento: "positivo" | "neutro" | "negativo";
  precisa_humano: boolean;
};

function isTicketOutput(value: unknown): value is TicketOutput {
  if (typeof value !== "object" || value === null) return false;

  const obj = value as Record<string, unknown>;

  return (
    ["billing", "technical", "account", "other"].includes(String(obj.categoria)) &&
    ["baixa", "media", "alta", "critica"].includes(String(obj.prioridade)) &&
    typeof obj.resumo === "string" &&
    ["positivo", "neutro", "negativo"].includes(String(obj.sentimento)) &&
    typeof obj.precisa_humano === "boolean"
  );
}

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "system",
        content:
          "Você é um classificador de tickets. Responda somente em json válido, sem Markdown, sem code fences e sem texto fora do JSON.",
      },
      {
        role: "user",
        content:
          "Classifique em json este ticket: Cliente relata cobrança duplicada e ameaça cancelar a assinatura.",
      },
    ],
    response_format: { type: "json_object" },
    max_tokens: 700,
    stream: false,
    // Parâmetro específico da DeepSeek. Se os tipos do SDK reclamarem,
    // mantenha a chamada em um wrapper tipado ou use validação própria.
    thinking: { type: "disabled" },
  } as any);

  const choice = completion.choices[0];

  if (choice.finish_reason === "length") {
    throw new Error("JSON possivelmente truncado. Aumente max_tokens.");
  }

  const content = choice.message.content ?? "";

  if (!content.trim()) {
    throw new Error("empty content retornado pela API.");
  }

  let parsed: unknown;

  try {
    parsed = JSON.parse(content);
  } catch (error) {
    throw new Error(`Falha em JSON.parse: ${(error as Error).message}`);
  }

  if (!isTicketOutput(parsed)) {
    throw new Error("JSON válido, mas schema incorreto.");
  }

  console.log(parsed);
}

main().catch(console.error);

A lição principal: JSON.parse confirma a sintaxe, mas não confirma se categoria, prioridade ou sentimento seguem o contrato esperado.

Como escrever um bom prompt para JSON Output

Um bom prompt para DeepSeek JSON Output reduz ambiguidade. Ele não deve apenas pedir “retorne JSON”. Ele deve explicar o papel do modelo, definir o objeto raiz, listar campos, tipos, enums, regras para valores desconhecidos e proibir texto fora do JSON.

Modelo de system prompt:

Você é um sistema de extração de dados.
Responda somente em json válido.
Não use Markdown.
Não use code fences.
Não escreva explicações antes ou depois do JSON.
O objeto raiz deve ser um objeto, não um array.
Use null para valores desconhecidos.
Siga exatamente os campos solicitados.

Modelo de user prompt:

Extraia os dados abaixo e retorne json neste formato:

{
  "nome_cliente": "string|null",
  "email": "string|null",
  "tipo_solicitacao": "suporte|vendas|financeiro|outro",
  "urgencia": "baixa|media|alta",
  "resumo": "string"
}

Texto:
"Olá, sou Ana Ribeiro. Meu e-mail é [email protected].
Preciso alterar a forma de pagamento da minha assinatura."

Boas práticas de prompt:

• inclua a palavra json;
• peça “somente JSON”;
• proíba Markdown e code fences;
• defina objeto raiz;
• liste campos obrigatórios;
• defina enums;
• explique quando usar null;
• limite arrays;
• peça strings curtas quando o campo for resumo;
• explique que não deve inventar dados ausentes.

DeepSeek JSON Output vs JSON Schema vs Tool Calls

Opção	O que gera	Onde aparece	Garante schema?	Melhor uso	Cuidado principal
Texto livre	Frases, listas, Markdown ou explicações	message.content	Não	Chat, respostas humanas, análise textual	Difícil de parsear
DeepSeek JSON Output	JSON válido	Normalmente em message.content	Não garante regras completas de negócio	Saída estruturada para automação	Validar schema no backend
JSON Schema no backend	Contrato formal de dados	Na aplicação	Sim, se aplicado corretamente	Validação de campos, tipos, enums e limites	Não gera resposta; apenas valida
Tool Calls	Solicitação de chamada de função	tool_calls	Parcial, conforme definição da ferramenta	Quando o modelo precisa acionar função externa	A função é executada pela sua aplicação
Tool Calls strict mode	Chamada de função mais aderente ao schema	tool_calls	Mais forte para argumentos de função	Integrações com funções externas	Na DeepSeek, strict mode é Beta e requer configuração específica

Function Calling permite que o modelo solicite o uso de ferramentas externas; a documentação da DeepSeek deixa claro que o modelo não executa a função sozinho, e que a funcionalidade real da função precisa ser fornecida pelo usuário ou pela aplicação. O strict mode, quando aplicável, busca aderência ao JSON Schema da função, mas é apresentado como Beta e exige base_url="https://api.deepseek.com/beta" e strict: true nas funções.

Use DeepSeek JSON Output quando você quer uma resposta estruturada. Use Tool Calls quando o modelo precisa pedir a execução de uma ação externa, como consultar estoque, criar um ticket, buscar clima, atualizar um CRM ou chamar uma API interna.

Qual modelo usar: deepseek-v4-flash ou deepseek-v4-pro?

A documentação atual da DeepSeek lista deepseek-v4-flash e deepseek-v4-pro como modelos disponíveis para o formato OpenAI, com suporte a JSON Output e Tool Calls. Também informa contexto de 1M e suporte a modos thinking e non-thinking.

Use deepseek-v4-flash para:

• extração simples;
• classificação de tickets;
• geração de metadados SEO;
• workflows de alto volume;
• tarefas com baixa ambiguidade;
• respostas curtas e previsíveis.

Use deepseek-v4-pro para:

• documentos longos;
• análise contratual;
• revisão de código;
• decisões estruturadas com mais contexto;
• classificação complexa;
• tarefas que exigem raciocínio mais robusto.

A DeepSeek também publicou que deepseek-chat e deepseek-reasoner estão programados para serem totalmente retirados após 24 de julho de 2026, 15:59 UTC, e que atualmente roteiam para modos do deepseek-v4-flash. Para projetos novos, prefira usar diretamente deepseek-v4-flash ou deepseek-v4-pro.

Como nomes de modelos, preços e limites podem mudar, revise a documentação oficial antes de alterações importantes em produção.

JSON Output com Thinking Mode

Thinking Mode pode ser útil quando a tarefa exige raciocínio mais profundo antes da resposta final. Na DeepSeek, o Thinking Mode é controlado pelo parâmetro thinking, e a documentação indica que reasoning_content é retornado no mesmo nível de content quando esse modo está ativo.

Use Thinking Mode em casos como:

• análise de contrato;
• documentos longos;
• classificação complexa;
• code review estruturado;
• decisões que exigem comparação de várias evidências.

Evite Thinking Mode em casos como:

• extração simples de campos;
• classificação direta;
• metadados SEO simples;
• workflows de alto volume;
• respostas que precisam de baixa latência.

Para JSON Output, o parsing final deve ser feito a partir de content, não de reasoning_content. O reasoning_content pode existir para apoiar o processo de raciocínio, mas a resposta estruturada que seu sistema consome deve ser o JSON final.

Validação no backend: por que JSON válido não é suficiente?

JSON válido apenas significa que a sintaxe pode ser parseada. Ele não garante que os campos estejam corretos, que os enums sejam permitidos, que datas façam sentido ou que o modelo não tenha inventado informação.

Exemplos de erros que ainda podem acontecer:

• prioridade: "urgente" quando o enum esperado era baixa|media|alta|critica;
• data impossível, como "2026-02-31";
• campo obrigatório ausente;
• score fora de faixa, como confianca: 1.7;
• campo booleano retornado como string;
• array com itens demais;
• valor alucinado em documento sem evidência.

Exemplo curto com Pydantic

Pydantic é uma biblioteca de validação de dados para Python baseada em type hints, e sua documentação destaca validação, serialização e suporte a JSON Schema.

from typing import Literal
from pydantic import BaseModel, Field, ValidationError

class TicketOutput(BaseModel):
    categoria: Literal["billing", "technical", "account", "other"]
    prioridade: Literal["baixa", "media", "alta", "critica"]
    resumo: str = Field(min_length=10, max_length=240)
    sentimento: Literal["positivo", "neutro", "negativo"]
    precisa_humano: bool

try:
    ticket = TicketOutput.model_validate(data)
except ValidationError as exc:
    print("JSON válido, mas dados inválidos:")
    print(exc)

Exemplo curto com Zod

Zod é uma biblioteca TypeScript-first para definir schemas e validar dados, de strings simples a objetos complexos.

import { z } from "zod";

const TicketSchema = z.object({
  categoria: z.enum(["billing", "technical", "account", "other"]),
  prioridade: z.enum(["baixa", "media", "alta", "critica"]),
  resumo: z.string().min(10).max(240),
  sentimento: z.enum(["positivo", "neutro", "negativo"]),
  precisa_humano: z.boolean(),
});

const ticket = TicketSchema.parse(parsed);

Essa validação deve acontecer antes de salvar dados, disparar automações, enviar respostas para clientes ou alimentar relatórios.

Erros comuns e troubleshooting

Problema	Causa provável	Como corrigir
Saída vazia	empty content ocasional ou prompt fraco	Reescreva o prompt, adicione exemplo JSON e retry limitado
Request parece travado	Prompt não pediu JSON explicitamente	Inclua a palavra json e “somente JSON”
Resposta cheia de espaços	Falta de instrução clara para produzir JSON	Use response_format e prompt explícito
JSON truncado	max_tokens insuficiente	Aumente max_tokens ou reduza o tamanho do output
finish_reason="length"	Limite de tokens ou contexto atingido	Não faça parsing; repita com limite maior
JSON.parse falha	Conteúdo não é JSON válido ou foi cortado	Capture SyntaxError, logue com segurança e faça retry
Markdown code block ao redor do JSON	Prompt permitiu Markdown	Diga “não use Markdown nem code fences”
Campos faltando	Schema pouco claro	Liste campos obrigatórios e exemplo completo
Schema drift	Mudanças no prompt ou no modelo	Versione o schema e monitore taxa de validação
Root array em vez de root object	Prompt não definiu objeto raiz	Peça “o objeto raiz deve ser um objeto”
Usar Tool Calls quando JSON Output bastava	Confusão entre estrutura e ação externa	Use JSON Output para resposta estruturada simples
Usar JSON Output quando Tool Calls era necessário	O sistema precisava chamar função externa	Use Tool Calls para ações e integrações

A documentação da DeepSeek menciona explicitamente o risco de conteúdo parcialmente cortado quando finish_reason="length" e também registra que a API pode ocasionalmente retornar conteúdo vazio ao usar JSON Output.

Boas práticas para produção

• Versione o schema: schema_version: "1.0".
• Valide sintaxe com json.loads ou JSON.parse.
• Valide estrutura com Pydantic, Zod ou JSON Schema.
• Não salve output bruto sem validação.
• Use retry limitado para parsing, truncamento e empty content.
• Não registre dados sensíveis em logs.
• Monitore taxa de parsing bem-sucedido.
• Monitore taxa de validação por campo.
• Defina fallback humano para casos críticos.
• Teste com dados reais e exemplos adversariais.
• Limite tamanho de arrays.
• Configure max_tokens com folga.
• Separe endpoints simples de endpoints complexos.
• Use deepseek-v4-flash para volume e deepseek-v4-pro para complexidade.
• Revise a documentação oficial antes de mudanças de modelo.
• Mantenha prompts e schemas em controle de versão.

Casos de uso práticos

1. Extração de e-mails

Objetivo: identificar remetente, assunto, intenção e dados acionáveis.

Formato esperado:

{
  "nome": "string|null",
  "email": "string|null",
  "intencao": "suporte|vendas|financeiro|outro",
  "resumo": "string",
  "dados_faltantes": ["string"]
}

Cuidado de validação: confirme formato de e-mail, limite tamanho de dados_faltantes e não aceite dados inventados.

2. Classificação de tickets de suporte

Objetivo: rotear tickets para filas internas.

Formato esperado:

{
  "categoria": "billing|technical|account|other",
  "prioridade": "baixa|media|alta|critica",
  "sentimento": "positivo|neutro|negativo",
  "precisa_humano": true
}

Cuidado de validação: use enums rígidos e defina regras para prioridade crítica.

3. Geração de metadados SEO

Objetivo: gerar title, description, slug e tags.

Formato esperado:

{
  "seo_title": "string",
  "meta_description": "string",
  "slug": "string",
  "tags": ["string"]
}

Cuidado de validação: limite caracteres de title e description, normalize slug e bloqueie tags duplicadas.

4. Normalização de produtos para catálogo

Objetivo: transformar descrições soltas em atributos padronizados.

Formato esperado:

{
  "nome_produto": "string",
  "marca": "string|null",
  "categoria": "string",
  "atributos": {
    "cor": "string|null",
    "tamanho": "string|null",
    "material": "string|null"
  }
}

Cuidado de validação: não aceitar marca inventada e manter enums para categorias.

5. Resumo estruturado de documentos

Objetivo: resumir documentos longos em blocos úteis.

Formato esperado:

{
  "titulo": "string",
  "resumo_executivo": "string",
  "pontos_chave": ["string"],
  "riscos": ["string"],
  "acoes_recomendadas": ["string"]
}

Cuidado de validação: limite número de itens e exija evidência textual quando o caso for crítico.

6. Revisão de código com severidade

Objetivo: retornar problemas encontrados em um formato consumível por ferramentas internas.

Formato esperado:

{
  "tem_problemas": true,
  "achados": [
    {
      "arquivo": "string|null",
      "linha": 0,
      "severidade": "baixa|media|alta|critica",
      "descricao": "string",
      "sugestao": "string"
    }
  ]
}

Cuidado de validação: limite quantidade de achados, valide severidade e trate linha como opcional quando o modelo não tiver essa informação.

Checklist final para implementar DeepSeek JSON Output

• Escolher deepseek-v4-flash ou deepseek-v4-pro.
• Usar Chat Completions API.
• Definir response_format: {"type":"json_object"}.
• Incluir a palavra json no prompt.
• Pedir “somente JSON”.
• Proibir Markdown e code fences.
• Definir objeto raiz.
• Fornecer exemplo do formato esperado.
• Listar campos obrigatórios.
• Definir enums e valores nulos.
• Configurar max_tokens suficiente.
• Ler message.content.
• Verificar finish_reason.
• Fazer parsing com json.loads ou JSON.parse.
• Validar schema com Pydantic, Zod ou JSON Schema.
• Monitorar erros e criar retry limitado.

FAQ sobre DeepSeek JSON Output

Conclusão

DeepSeek JSON Output é a forma mais direta de gerar saída estruturada na DeepSeek API quando sua aplicação precisa consumir objetos JSON em vez de texto livre. A implementação correta combina response_format: {"type":"json_object"}, prompt claro com a palavra json, exemplo do formato esperado, max_tokens suficiente, parsing de message.content, verificação de finish_reason e validação no backend.

Para tarefas simples e de alto volume, deepseek-v4-flash tende a ser a escolha prática. Para documentos longos, análise complexa e decisões estruturadas, deepseek-v4-pro pode ser mais adequado. Em todos os casos, trate o JSON como entrada não confiável até passar por validação. DeepSeek JSON Output melhora a previsibilidade da resposta, mas produção exige schema, logs seguros, retries limitados, monitoramento e fallback para casos críticos.