Receba saídas estruturadas
Envie um JSON Schema para o modelo retornar JSON no seu formato e valide o resultado antes de usá-lo.
Envie um JSON Schema com a solicitação, e o modelo retorna JSON nesse formato em vez de texto livre. Use isso quando você quer dados de volta, como campos extraídos de um e-mail. Use chamadas de ferramentas quando você quer que o modelo peça ao seu app para fazer algo.
type | O que você recebe |
|---|---|
json_schema | JSON que segue o seu schema. Use este por padrão. |
json_object | Algum objeto JSON válido, sem formato garantido. |
text | Texto simples (o padrão). |
O formato vai em response_format no /v1/chat/completions, em text.format no /v1/responses e em output_config.format no /v1/messages (só json_schema).
{
"model": "openai/gpt-6-astra",
"messages": [
{ "role": "user", "content": "Return the city and weather for London." }
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "weather",
"strict": true,
"schema": {
"type": "object",
"properties": {
"city": { "type": "string" },
"weather": { "type": "string" }
},
"required": ["city", "weather"],
"additionalProperties": false
}
}
}
}
O JSON volta como string no conteúdo da mensagem. Antes de interpretá-lo, verifique se houve recusa, conteúdo ausente ou um finish_reason diferente de stop. Depois valide o objeto interpretado, por exemplo com Zod. Se a validação falhar, tente de novo uma vez com o erro no prompt e então retorne uma falha segura. Cada nova tentativa é cobrada, e JSON válido ainda não prova que os valores estão corretos.
O Phaseo nunca descarta response_format. Ele só roteia uma solicitação json_schema para provedores que aceitam saídas estruturadas; se nenhum provedor do modelo aceitar, a solicitação falha com 400 validation_error. As páginas de modelo indicam o suporte com structured_outputs, que é um indicador de capacidade, não um campo da solicitação.
Confira o que você aprendeu
Você envia response_format com json_schema para um modelo cujos provedores não aceitam saídas estruturadas. O que acontece?
Aplique
O seu leitor de faturas usa json_schema e, de vez em quando, a resposta falha na sua verificação com Zod porque total está ausente. O que o código deve fazer?
Mostrar a respostaOcultar a resposta
Primeiro confira se finish_reason é stop, já que uma resposta cortada não pode ser válida. Depois tente de novo uma vez com o erro de validação no prompt e, se falhar outra vez, retorne uma falha segura em vez de adivinhar. Acompanhe as falhas por modelo e por versão do schema para perceber quando uma mudança em qualquer um deles piora as coisas.
Resumo
json_schema para dados que você precisa em um formato fixo e sempre valide o resultado no seu próprio código antes de confiar nele.Links relacionados
Verificado em 17 de novembro de 2026