Receber JSON no formato combinado em toda chamada de API

Para receber JSON que outro sistema consome sem conferência manual, declare o esquema na chamada da API em modo estrito, deixe o modelo raciocinar antes de preencher os campos e valide no código o que o esquema não cobre. Vale para quem liga IA a CRM, ERP ou planilha, e a ação de hoje é migrar um fluxo.

Pedir "responda só em JSON" no prompt funciona na demonstração, com cinco exemplos escolhidos por quem a montou. Em produção chegam milhares de mensagens por mês que ninguém escolheu, e aparecem a vírgula sobrando, o campo que falta, o valor em reais escrito como texto e a categoria que ninguém combinou. Só o primeiro desses erros dispara exceção no sistema; os outros entram na base e aparecem na conciliação do mês seguinte.

JSON é o formato de texto que sistemas usam para trocar dados, parecido com um formulário de campos nomeados. Entre 2024 e 2026, Anthropic, OpenAI, Google e xAI passaram a aceitar a descrição desse formulário dentro da própria chamada, e a geração fica restrita a ela. Com isso, o formato sai do texto do pedido e vai para a configuração, onde a obediência do modelo deixa de decidir.

Saída estruturada (structured outputs) é o recurso em que a aplicação envia um JSON Schema, o molde que lista campos, tipos, obrigatórios e valores permitidos. A plataforma aplica decodificação restrita: a cada pedaço de texto gerado, o modelo só pode escolher o que o molde aceita, como um formulário que recusa letra no campo de CPF. JSON inválido, campo a mais e categoria fora da lista deixam de ser possíveis. Quando a OpenAI lançou o recurso, em agosto de 2024, mediu 100% de aderência a esquemas complexos, contra menos de 40% do gpt-4-0613 guiado só pelo prompt.

Na Anthropic, o recurso está em disponibilidade geral, sem cabeçalho beta, em duas formas que se combinam. O JSON da resposta vai em output_config.format com o tipo json_schema; cada ferramenta (função que o modelo pode chamar) ganha strict: true na definição. O parâmetro antigo output_format está depreciado. O pré-preenchimento (prefill, começar a resposta do assistente com uma chave aberta para forçar JSON) devolve erro 400 desde a geração 4.6, e o substituto indicado é o próprio esquema.

Modo JSON é a opção mais antiga, ainda oferecida pela OpenAI e pela xAI com o nome json_object: entrega JSON sintaticamente válido sem conferir os campos. A diferença decide propostas de fornecedor. O modo JSON garante um JSON qualquer; o modo estrito garante o seu esquema. Nenhum dos dois confere a verdade do conteúdo, porque um valor pode obedecer ao contrato e ter vindo da linha errada do e-mail.

Os quatro fornecedores partem do mesmo JSON Schema e aceitam pedaços diferentes dele. Um esquema com mínimo numérico passa no Gemini e é recusado no Claude; um esquema com campo opcional passa no Claude e precisa de ajuste na OpenAI, que exige todos os campos na lista de obrigatórios. O desenho que viaja entre os quatro marca tudo como obrigatório, representa a ausência com null e deixa faixas e tamanhos para o código.

Raciocinar antes de formatar

Restrição de formato cobra um preço quando a tarefa pede raciocínio. No estudo "Let Me Speak Freely?" (Tam et al., EMNLP 2024), o acerto em problemas de matemática do GSM8K caiu 17% no LLaMA-3-8B e 24% no Gemini-1.5-Flash quando a resposta saía em modo JSON em vez de texto livre. A equipe da .txt refez o teste com decodificação restrita de verdade e o mesmo prompt nas duas condições, e a queda sumiu: 0,77 sem estrutura contra 0,78 com estrutura.

As duas leituras apontam para a ordem de geração: quando o esquema põe o campo da resposta antes de qualquer espaço para pensar, o modelo decide antes de raciocinar. A correção é de ordem. Deixe o modelo pensar primeiro, pelo raciocínio nativo (effort no Claude, reasoning.effort na OpenAI, thinking_level no Gemini) ou por um campo de evidências posto antes dos campos de decisão. Como o texto sai em sequência, o campo que vem primeiro no esquema é escrito primeiro, e a ordem das propriedades passa a ser instrução.

O mesmo desenho de esquema resolve trabalhos de áreas diferentes. O padrão se repete: lista fechada para o que vira filtro ou relatório, null para o que pode faltar, evidência literal antes da decisão e validação no código para faixa de valor e data.

Extrair lead de e-mail para o CRM

O caso mais comum em marketing e vendas é o texto solto que precisa virar registro com campos. O guia abaixo usa um e-mail fictício e um esquema que roda igual no Claude e, com o invólucro trocado, na OpenAI.

Três campos mostram o esquema fazendo o trabalho. O orçamento chega null porque o e-mail diz que ainda não foi fechado, e a regra dois impede o número plausível inventado. O prazo exige conta: a primeira semana de novembro fica a menos de 30 dias de 13/10/2026, e a evidência copiada antes da decisão deixa a conta à vista de quem confere. O telefone sai só com dígitos, pronto para o discador.

Para levar o mesmo esquema à OpenAI, troque o invólucro por text.format com type json_schema, um name como lead_crm e strict: true; como todos os campos já estão em required e a ausência é null, nada mais muda. No Playground do Claude Console, o modelo Extrair dados estruturados já vem com o formato de saída por esquema ligado.

Os erros que sobram depois do esquema ligado são de conteúdo e de operação, e aparecem justamente porque o painel de JSON válido fica verde.

Faça hoje

Escolha o fluxo em que a resposta da IA entra direto num sistema e que ainda depende de "responda só em JSON" no prompt. Em 30 minutos, escreva o esquema com as evidências antes das decisões, declare-o na chamada do fornecedor que você usa e rode as últimas 20 entradas reais. Deu certo quando as 20 respostas passam pelo parser sem retentativa e a conferência de cinco delas contra o texto original não encontra campo inventado.