O que é saída estruturada?

A saída estruturada faz com que um modelo de linguagem retorne JSON que seu código pode analisar em vez de texto livre. O modo JSON retorna um objeto JSON sintaticamente válido, e o esquema JSON vai além fazendo a resposta corresponder a um esquema que você definir, com seus campos e tipos obrigatórios.

Conceitos

Por que a produção estruturada importa

Aplicações frequentemente precisam da resposta de um modelo como dados: campos extraídos de uma fatura, uma etiqueta para um ticket de suporte, os passos de um plano, um registro a salvar. Pedir JSON no prompt funciona na maior parte do tempo, mas texto livre pode chegar com uma explicação antes do JSON, uma cerca de código ao redor, um campo ausente ou um número escrito como uma string. Cada um desses quebra um parser.

A saída estruturada restringe a própria geração. A resposta é JSON válida e, com um esquema, ela também tem exatamente a forma que você pediu.

Modo JSON e esquema JSON

Existem dois níveis, ambos definidos com response_format:

  • Modo JSON. {"tipo": "json_object"} faz o modelo retornar um objeto JSON válido. Você descreve os campos desejados no prompt, e a forma não é aplicada.
  • Esquema JSON. {"type": "json_schema", "json_schema": {...}} toma um Nome, a Esquema e rígido, e faz com que a saída se conforme aquele Esquema JSON: campos obrigatórios presentes, tipos corretos e sem chaves extras ao definir additionalProperties para falso.

Use o esquema JSON quando o modelo o suportar e seu código depender de campos exatos. Marque cada campo que seu código lê como necessário, use enum Para escolhas fixas, mantenha o aninhamento raso e adicione um curto Descrição a qualquer campo cujo significado não seja evidente pelo nome.

Para um extrator de faturas, um esquema pode exigir Vendedor como uma corda, Total como número, Moeda como um enum dos códigos que você aceita, e line_items como um array de objetos com Descrição e Valor. Com rígido definir para Verdade, cada resposta carrega esses campos com esses tipos, para que seu código leia as mesmas chaves toda vez. No modo JSON, coloque um objeto de exemplo curto no prompt, para que o modelo tenha uma forma a seguir.

Suporte por modelo e endpoint

O suporte é configurado por modelo. O structured_output campo ligado VÁ /v1/models/{model} Leituras json_schema quando o modelo suporta esquemas e json_object quando suporta apenas o modo JSON, e os modelos nesta página mostram qual nível cada um tem. Enviar um formato que o modelo não suporta retorna 400.

O mesmo recurso funciona em cada endpoint de texto, na forma própria desse endpoint:

  • /v1/chat/completions e /v1/completions: response_format.
  • /v1/responses: text.format.
  • /v1/messages: output_config.format, ou um response_format ao lado do resto do pedido.

No Playground, modelos de chat que o suportam possuem um modo Desligado, modo JSON e controle de esquema JSON, com uma caixa para o seu esquema. O Guia de compatibilidade possui exemplos completos de solicitações.

Orientação prática

  • Valide mesmo assim. Analisar e verificar cada resposta no código. Uma resposta interrompida pelo limite de saída, reportada como finish_reason Comprimento, é JSON incompleto, portanto definido max_tokens Alto o suficiente para o maior objeto que você espera.
  • Verifique modelos de raciocínio. Em alguns modelos, um pedido com response_format respostas sem raciocínio, a menos que também defina activar pensar.
  • Modelos sem suporte. Peça JSON no prompt, inclua um exemplo da forma e valide o resultado.
  • Escolha o recurso certo. Use saída estruturada quando o JSON for a resposta final. Use chamada de função quando o modelo deve escolher uma ação para o seu código executar.

Navegar Modelos de texto para comparar quais suportam cada nível.

Suporte a saída estruturada por modelo

62 modelos. A página de cada modelo traz a tabela de preços, os parâmetros e código.

ModeloSaída estruturadaJanela de contexto
DeepSeek V4 Pro DeepSeekJSON Schema1M tokens
DeepSeek V4 Pro 0813 DeepSeekJSON Schema1M tokens
Fugu Max Sakana AIJSON Schema1M tokens
Fugu Ultra v1.1 Sakana AIJSON Schema1M tokens
Fugu Ultra v2.0 Sakana AIJSON Schema1M tokens
Gemma 4 26B-A4B GoogleJSON Schema256K tokens
Kimi K2.6 Moonshot AIJSON Schema256K tokens
Kimi K2.7 Code Moonshot AIJSON Schema256K tokens
Ver todos os 62 modelos
ModeloSaída estruturadaJanela de contexto
Kimi K2.7 Code Highspeed Moonshot AIJSON Schema256K tokens
Kimi K3 Moonshot AIJSON Schema1M tokens
Kimi K3.1 Pro Moonshot AIJSON Schema1M tokens
MiMo V2.6 Flash XiaomiJSON Schema1M tokens
MiMo V2.6 Pro XiaomiJSON Schema1M tokens
MiMo V2.6 Pro UltraSpeed XiaomiJSON Schema1M tokens
Mistral Small 3.1 Mistral AIJSON Schema89.6K tokens
Muse Glimmer 30B Meta AIJSON Schema128K tokens
Muse Spark 1.1 Meta AIJSON Schema1M tokens
Muse Spark 1.2 Meta AIJSON Schema1M tokens
Muse Spark 1.3 Meta AIJSON Schema1M tokens
Qwen3.5 4B Alibaba CloudJSON Schema256K tokens
Qwen3.5 9B Alibaba CloudJSON Schema256K tokens
Qwen3.5 Omni Plus Alibaba CloudJSON Schema192K tokens
Qwen3.6 35B A3B Alibaba CloudJSON Schema128K tokens
Qwen3.7 Flash Alibaba CloudJSON Schema983.6K tokens
Qwen3.7 Max Alibaba CloudJSON Schema983.6K tokens
Qwen3.7 Plus Alibaba CloudJSON Schema983.6K tokens
Qwen3.8 27B Alibaba CloudJSON Schema256K tokens
Qwen3.8 Flash Alibaba CloudJSON Schema983.6K tokens
Qwen3.8 Max Alibaba CloudJSON Schema983.6K tokens
Qwen3.8 Max 0902 Alibaba CloudJSON Schema983.6K tokens
Qwen3.8 Omni Flash Alibaba CloudJSON Schema1.01M tokens
Qwen4 Max Alibaba CloudJSON Schema983.6K tokens
Seed 2.0 Lite ByteDanceJSON Schema229.1K tokens
Seed 2.0 Mini ByteDanceJSON Schema229.2K tokens
Seed 2.0 Pro ByteDanceJSON Schema229.1K tokens
Seed 2.1 Turbo ByteDanceJSON Schema229.1K tokens
Step 5 Preview StepFunJSON Schema1.02M tokens
DeepSeek V4 Flash 0731 DeepSeekModo JSON1M tokens
DeepSeek V4.1 Flash 1017 DeepSeekModo JSON1M tokens
Fugu Ultra v1.0 Sakana AIModo JSON1M tokens
GLM 4.5 Flash Z.aiModo JSON128K tokens
GLM 4.6V Flash Z.aiModo JSON128K tokens
GLM 4.6V FlashX Z.aiModo JSON128K tokens
GLM 4.7 Flash Z.aiModo JSON202.8K tokens
GLM 4.7 FlashX Z.aiModo JSON202.8K tokens
GLM 5.1 Z.aiModo JSON202.7K tokens
GLM 5.2 Z.aiModo JSON1M tokens
GLM 5.3 Z.aiModo JSON1M tokens
GLM 5.3 Flash Z.aiModo JSON1M tokens
Mistral Small 4 Mistral AIModo JSON256K tokens
Qwen3.5 122B-A10B Alibaba CloudModo JSON258K tokens
Qwen3.5 27B Alibaba CloudModo JSON258K tokens
Qwen3.5 35B-A3B Alibaba CloudModo JSON258K tokens
Qwen3.5 397B-A17B Alibaba CloudModo JSON258K tokens
Qwen3.5 Flash Alibaba CloudModo JSON995.9K tokens
Qwen3.5 Plus Alibaba CloudModo JSON983.6K tokens
Qwen3.6 27B Alibaba CloudModo JSON224K tokens
Qwen3.6 Flash Alibaba CloudModo JSON983.6K tokens
Qwen3.6 Plus Alibaba CloudModo JSON983.6K tokens
Step 3.7 Flash StepFunModo JSON256K tokens
StepAudio 2.5 Chat StepFunModo JSON256K tokens
StepAudio 3 Chat StepFunModo JSON256K tokens

Perguntas frequentes

Qual é a diferença entre o modo JSON e o esquema JSON?

O modo JSON retorna um objeto JSON válido, mas deixa sua forma para o seu prompt. O esquema JSON faz com que a resposta corresponda a um esquema que você fornece, incluindo campos e tipos obrigatórios.

Quais modelos suportam saída estruturada?

O suporte é por modelo. O campo structured_output de cada modelo lê json_schema para suporte a esquema ou json_object apenas para modo JSON, e uma solicitação para um formato não suportado retorna um erro 400.

Ainda preciso validar o JSON?

Sim. Uma resposta pode ser interrompida pelo limite de saída, e sua aplicação pode ter regras que um esquema não pode expressar, portanto, analise e valide cada resposta.

Posso usar saída estruturada com os endpoints Respostas ou Mensagens?

Sim. O endpoint Respostas usa text.format, e o endpoint Mensagens aceita output_config.format ou um campo response_format.

Pronto para usar endpoints melhores?

Confira nossos preços ou entre em contato se quiser que seu próprio modelo seja implementado em nossa pilha.