As saídas estruturadas permitem exigir um formato legível por máquina em vez de texto livre.
Compatibilidade dos endpoints
Use saídas estruturadas em:
/v1/chat/completions com response_format
/v1/responses com text.format
/v1/messages ainda pode retornar texto JSON, mas não usa o mesmo contrato de response_format.
Solicitação
Resposta
Observações sobre o contrato
response_format.type deve ser text, json_object ou json_schema.
- Para
json_schema, inclua um objeto de schema (response_format.json_schema.schema em payloads no estilo chat ou text.format.schema em payloads no estilo Responses).
- Valide o JSON no servidor antes de usá-lo em etapas posteriores.
Projete seu esquema
Comece com um objeto pequeno, marque explicitamente os campos obrigatórios e use enumerações para categorias conhecidas. Defina additionalProperties: false para rejeitar chaves extras. Mantenha o esquema solicitado e o validador do servidor sincronizados; versione-os juntos.
Valide o resultado
Analise e valide o resultado completo antes de usá-lo nas próximas etapas. Este exemplo de TypeScript usa Zod e corresponde ao esquema meteorológico acima:
Trate recusas, conteúdo ausente e respostas truncadas antes de analisar. Se a validação falhar, permita apenas um número limitado de tentativas corretivas e depois retorne uma falha segura. Novas gerações podem gerar cobranças adicionais. JSON válido não comprova a exatidão factual dos valores nem autoriza uma ação.
Acompanhe falhas de validação por modelo e versão do esquema. Reavalie os casos de teste quando qualquer um mudar. Para recuperar JSON malformado, veja reparo de respostas. Última modificação em 2 de outubro de 2026