DeepSeek JSON Output: como gerar, analisar e validar JSON

Verificação editorial: 19 de julho de 2026. Este guia cobre o recurso JSON Output da API oficial hospedada pela DeepSeek nessa data, usando deepseek-v4-flash e deepseek-v4-pro.

Teste ao vivo: JSON válido e parseável

Testamos JSON Output em uma chamada autenticada e não streaming com V4 Flash, Thinking desativado e response_format: {"type":"json_object"}.

Item	Resultado
HTTP	200
Latência observada	325 ms
Conteúdo exato	{"status":"ok"}
JSON.parse()	Concluído sem erro
Entrada / saída / total	49 / 5 / 54
Cache hit / miss	0 / 49

O teste confirma apenas que esta chamada mínima retornou JSON sintaticamente válido. Não garante campos, tipos, enums, datas ou regras de negócio. Em produção, valide schema e trate finish_reason="length" antes do parsing.

Uma chamada simples não mede estabilidade em volume, schemas complexos, streaming ou respostas longas. Nenhum raciocínio bruto foi publicado.

Compare com Tool Calls, Error Codes e a documentação oficial.

Aviso de independência: DeepSeek Português é um guia de terceiros e não representa a DeepSeek. Os links oficiais estão identificados ao final da página.

O DeepSeek JSON Output faz a resposta de Chat Completions chegar como uma string JSON válida. Para ativá-lo, envie response_format: {"type":"json_object"}, mencione a palavra json no prompt, forneça um exemplo do formato desejado e reserve max_tokens suficiente.

Limite essencial: JSON Output garante o formato JSON da resposta normal, mas não garante que campos, tipos, valores ou regras do seu negócio estejam corretos. Faça JSON.parse e valide o objeto no servidor antes de salvar dados, chamar APIs ou executar ações.

Configuração mínima correta

1. Use POST https://api.deepseek.com/chat/completions.
2. Escolha deepseek-v4-flash ou deepseek-v4-pro.
3. Defina response_format.type como json_object.
4. Inclua a palavra json na mensagem de sistema ou do usuário.
5. Mostre um exemplo do objeto JSON esperado.
6. Defina max_tokens de acordo com o tamanho esperado.
7. Confirme finish_reason, trate conteúdo vazio, faça o parsing e valide o resultado.

Sem uma instrução explícita para produzir JSON, a referência da API alerta que o modelo pode gerar espaços em branco continuamente até atingir o limite de tokens, dando a impressão de que a chamada travou. Escrever apenas “responda de forma estruturada” não atende à orientação oficial: use literalmente json.

Modelos compatíveis e limites

Model ID	JSON Output	Contexto	Saída máxima	Thinking padrão
deepseek-v4-flash	Sim	1 milhão de tokens	384 mil tokens	Ativado
deepseek-v4-pro	Sim	1 milhão de tokens	384 mil tokens	Ativado

Use Flash para extração e automação em volume quando ele cumprir seus testes; considere Pro para tarefas mais ambíguas ou complexas. Ambos aceitam Thinking e Non-Thinking. Nos exemplos de extração direta abaixo, o Thinking Mode é desativado explicitamente para evitar raciocínio desnecessário. Consulte DeepSeek V4: Flash e Pro, a visão geral da API DeepSeek e o guia de Thinking Mode.

O prazo anunciado já passou. Em 29/07/2026, ambos os aliases ainda responderam HTTP 200 nesta conta e retornaram V4 Flash, mas não apareceram em GET /models. Isso é compatibilidade residual observada, não garantia. Use IDs V4 explícitos.

Exemplo completo em Node.js

Instale o SDK com npm install openai. A chave deve ficar em variável de ambiente no backend; não a coloque no HTML, no JavaScript do navegador, em um aplicativo distribuído ou em um repositório.

import OpenAI from "openai";

const apiKey = process.env.DEEPSEEK_API_KEY;
if (!apiKey) throw new Error("Defina DEEPSEEK_API_KEY no servidor.");

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

const systemPrompt = `
Extraia os dados do texto e retorne somente um objeto json.
Não use Markdown e não acrescente explicações.

Exemplo de json esperado:
{
  "pedido_id": "PED-100",
  "cliente": "Ana",
  "itens": 2,
  "prioridade": "normal"
}
`;

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: systemPrompt },
    {
      role: "user",
      content: "Pedido PED-482, cliente Bruno, 3 itens, prioridade alta.",
    },
  ],
  response_format: { type: "json_object" },
  thinking: { type: "disabled" },
  max_tokens: 500,
});

const choice = response.choices[0];
if (!choice) throw new Error("A API não retornou uma choice.");

if (choice.finish_reason === "length") {
  throw new Error("JSON truncado: aumente max_tokens ou reduza a entrada.");
}
if (choice.finish_reason !== "stop") {
  throw new Error(`Geração encerrada por: ${choice.finish_reason}`);
}

const raw = choice.message.content ?? "";
if (!raw.trim()) throw new Error("A API retornou conteúdo vazio.");

let data;
try {
  data = JSON.parse(raw);
} catch (error) {
  throw new Error(`A resposta não pôde ser analisada como JSON: ${error.message}`);
}

function validarPedido(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  return (
    typeof value.pedido_id === "string" &&
    typeof value.cliente === "string" &&
    Number.isInteger(value.itens) &&
    value.itens >= 0 &&
    ["baixa", "normal", "alta"].includes(value.prioridade)
  );
}

if (!validarPedido(data)) {
  throw new Error("JSON válido, mas incompatível com o schema do aplicativo.");
}

console.log(data);

Este fluxo separa três verificações diferentes: encerramento da geração, sintaxe JSON e regras do aplicativo. Um objeto como {"pedido_id":123} pode ser JSON válido e ainda ser inadequado porque o ID deveria ser string e outros campos estão ausentes.

Exemplo equivalente em Python

import json
import os
from openai import OpenAI

api_key = os.environ.get("DEEPSEEK_API_KEY")
if not api_key:
    raise RuntimeError("Defina DEEPSEEK_API_KEY no servidor.")

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

system_prompt = """
Extraia título, idioma e número de palavras.
Retorne somente um objeto json, sem Markdown.
Exemplo de json:
{"titulo":"Guia","idioma":"pt-BR","palavras":1200}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "Título: API segura; idioma pt-BR; 850 palavras."},
    ],
    response_format={"type": "json_object"},
    max_tokens=300,
    extra_body={"thinking": {"type": "disabled"}},
)

choice = response.choices[0]
if choice.finish_reason == "length":
    raise RuntimeError("JSON truncado: ajuste max_tokens ou a entrada.")
if choice.finish_reason != "stop":
    raise RuntimeError(f"Geração encerrada por: {choice.finish_reason}")

raw = choice.message.content or ""
if not raw.strip():
    raise RuntimeError("A API retornou conteúdo vazio.")

try:
    data = json.loads(raw)
except json.JSONDecodeError as error:
    raise RuntimeError(f"JSON inválido ou incompleto: {error}") from error

required = {"titulo": str, "idioma": str, "palavras": int}
for field, expected_type in required.items():
    if field not in data or not isinstance(data[field], expected_type):
        raise RuntimeError(f"Campo inválido ou ausente: {field}")

print(data)

Para schemas extensos, use uma biblioteca de validação mantida para seu ecossistema. Mesmo assim, mantenha validações de domínio — por exemplo, status permitidos, limites numéricos, IDs existentes e permissões do usuário.

Streaming de JSON sem quebrar o parser

Durante streaming, cada delta é apenas um fragmento: {, uma parte de uma string ou metade de um número não são documentos JSON completos. Acumule delta.content e faça JSON.parse somente depois do fim do stream.

const stream = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "system",
      content: 'Retorne somente json. Exemplo: {"resumo":"...","tags":["..."]}',
    },
    { role: "user", content: "Resuma: ..." },
  ],
  response_format: { type: "json_object" },
  thinking: { type: "disabled" },
  max_tokens: 800,
  stream: true,
});

let raw = "";
let finishReason = null;

for await (const chunk of stream) {
  const choice = chunk.choices[0];
  if (!choice) continue;
  raw += choice.delta?.content ?? "";
  if (choice.finish_reason) finishReason = choice.finish_reason;
}

if (finishReason === "length") throw new Error("JSON truncado.");
if (finishReason !== "stop") throw new Error(`Fim inesperado: ${finishReason}`);
if (!raw.trim()) throw new Error("Conteúdo vazio.");

const data = JSON.parse(raw);
console.log(data);

Se o stream for interrompido pela rede, descarte o buffer parcial ou aplique uma estratégia de retomada idempotente. Não tente “consertar” silenciosamente JSON cortado e depois gravá-lo como se fosse uma resposta confiável.

JSON vazio, truncado ou não analisável

Sintoma	Causa provável	Tratamento
String vazia	O JSON Output pode ocasionalmente retornar conteúdo vazio	Ajuste o prompt e faça poucas tentativas com backoff; nunca aceite como objeto válido
Muitos espaços ou chamada “travada”	O prompt não instruiu explicitamente a saída em json	Inclua a palavra json e um exemplo
finish_reason: "length"	Limite de saída ou contexto atingido	Aumente max_tokens dentro dos limites ou reduza entrada/formato
JSON.parse falha	Conteúdo vazio, truncamento, stream parcial ou transformação da resposta	Não processe; registre o caso e gere novamente de forma controlada
JSON válido com valores errados	JSON mode não garante semântica ou regra de negócio	Valide schema, enums, intervalos, referências e permissões

A documentação reconhece especificamente a possibilidade de conteúdo vazio e recomenda modificar o prompt. Um retry deve ser limitado, usar backoff com jitter e ter idempotency control quando a chamada participa de um fluxo de gravação. Não presuma que uma resposta vazia ou falha não gera custo; reconcilie o uso retornado e sua conta.

JSON Output, JSON Schema e tool calls não são a mesma coisa

Recurso	O que entrega	O que não garante
JSON Output	Resposta do assistant como JSON sintaticamente válido via json_object	Conformidade com seu schema de negócio
Validação no backend	Regras de campos, tipos, enums e domínio definidas pela aplicação	Que os fatos extraídos pelo modelo sejam verdadeiros
Tool Calls	Pedido para sua aplicação executar uma função, com argumentos em JSON	Execução automática, permissão ou argumentos confiáveis
Tool Calls strict mode (Beta)	Argumentos aderentes ao JSON Schema suportado da função	Saída geral do assistant em um schema arbitrário ou correção semântica

A documentação do JSON Output registra apenas response_format: {"type":"json_object"}; ela não documenta um tipo json_schema para a resposta geral. Se você encontrar exemplos de outros provedores com response_format.type: "json_schema", não os copie para a DeepSeek sem confirmação oficial.

Onde existe JSON Schema oficial: tool calls strict (Beta)

O uso documentado de JSON Schema estrito está separado em Tool Calls strict mode. Ele exige a base URL Beta https://api.deepseek.com/beta, strict: true em todas as funções e um schema aceito pelo servidor. Em objetos, todas as propriedades devem constar em required e additionalProperties deve ser false.

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

const tools = [{
  type: "function",
  function: {
    name: "salvar_classificacao",
    description: "Salva uma classificação já validada pela aplicação.",
    strict: true,
    parameters: {
      type: "object",
      properties: {
        categoria: { type: "string", enum: ["suporte", "vendas", "financeiro"] },
        urgente: { type: "boolean" },
      },
      required: ["categoria", "urgente"],
      additionalProperties: false,
    },
  },
}];

Esse trecho apenas define a ferramenta; sua aplicação ainda precisa receber a tool call, validar autorização, executar a função e devolver o resultado. Como o modo é Beta e aceita um subconjunto de JSON Schema, confira a documentação antes de adotar cada keyword.

Prompts melhores para JSON Output

• Escreva “retorne somente um objeto json”, não apenas “estruture a resposta”.
• Inclua um exemplo pequeno com todas as chaves esperadas.
• Defina como representar valores ausentes: null, string vazia ou omissão — e valide a escolha.
• Liste enums permitidos e unidades, como centavos em vez de valor decimal ambíguo.
• Peça uma chave de evidência quando a extração precisar ser auditável.
• Delimite texto não confiável e instrua o modelo a tratá-lo como dados, não como comandos.
• Evite schemas gigantes em uma única chamada; divida o trabalho se isso melhorar testes e recuperação.

O exemplo no prompt melhora a aderência, mas continua sendo orientação probabilística. Sua camada de validação é o limite de confiança.

Checklist de produção

• Chave de API armazenada somente no servidor.
• ID explícito: deepseek-v4-flash ou deepseek-v4-pro.
• response_format.type: "json_object".
• A palavra json e um exemplo no prompt.
• max_tokens dimensionado e finish_reason verificado.
• Conteúdo vazio rejeitado.
• Parsing com tratamento de exceção.
• Schema e regras de negócio validados.
• Dados factuais verificados quando a precisão importa.
• Retries limitados, backoff e operações idempotentes.
• Logs sem chaves, credenciais ou dados pessoais desnecessários.

Para diagnosticar respostas interrompidas, autenticação e falhas de capacidade, use DeepSeek error codes e DeepSeek não funciona: troubleshooting. Para integração completa, consulte OpenAI SDK com DeepSeek.

FAQ sobre DeepSeek JSON Output

Qual response_format devo usar?

Use {"type":"json_object"}. Também instrua o modelo a produzir json na mensagem de sistema ou do usuário.

JSON Output garante meu schema?

Não. Ele garante JSON sintaticamente válido em uma geração normal concluída, mas não a presença, o tipo ou o significado dos campos. Valide o objeto no backend.

Por que a resposta veio vazia?

A documentação oficial diz que JSON Output pode ocasionalmente retornar conteúdo vazio. Rejeite a resposta, ajuste o prompt e tente novamente com um limite controlado.

Posso analisar cada chunk do streaming?

Não como documento completo. Acumule os fragmentos e faça o parsing depois de receber o término com finish_reason: "stop".

Preciso ativar Thinking Mode para gerar JSON?

Não. JSON Output é um recurso separado. Para extração direta, Non-Thinking pode ser mais eficiente; para tarefas complexas, teste Thinking e compare qualidade, latência e tokens.

Tool call strict é o mesmo que JSON Output?

Não. Strict mode é um recurso Beta para argumentos de funções e exige a URL Beta e schemas compatíveis. JSON Output controla a mensagem JSON do assistant via response_format.

Fontes oficiais

• DeepSeek API Docs — JSON Output
• DeepSeek API Reference — Create Chat Completion
• DeepSeek API Docs — Tool Calls e strict mode
• DeepSeek API Docs — Models & Pricing
• DeepSeek API Reference — List Models

DeepSeek Português é um site independente, criado por terceiros, sem afiliação, endosso ou representação oficial da DeepSeek. Confirme modelos, parâmetros e limites na documentação oficial antes de decisões de produção.