FlowModels

Receber respostas em JSON: response_format com json_object e json_schema

Publicado em 11. novembro 2026

Quando sua aplicação processa a resposta do modelo, você precisa de JSON limpo em vez de texto corrido. Para isso existe o campo response_format. Ele tem dois graus: com json_object você recebe JSON válido em qualquer formato, e com json_schema você define a estrutura exata.

As três variantes

Valor Resultado
{"type": "text"} texto normal, que também é o padrão
{"type": "json_object"} JSON válido, com a estrutura definida pelo modelo
{"type": "json_schema", "json_schema": {…}} JSON seguindo o seu schema

Qualquer JSON com json_object

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "system", "content": "Responda em JSON com os campos assunto e prioridade."},
    {"role": "user", "content": "O cliente escreve: nosso login não funciona desde hoje de manhã."}
  ],
  "response_format": {"type": "json_object"}
}

Mesmo assim, descreva no prompt quais campos você espera. O json_object garante apenas que a saída seja JSON válido, não que tenha determinados campos. Alguns provedores exigem que a palavra “JSON” apareça no prompt. Se ela não estiver em nenhuma mensagem, adicionamos automaticamente uma observação curta.

Uma estrutura fixa com json_schema

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "O cliente escreve: nosso login não funciona desde hoje de manhã."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "assunto": {"type": "string"},
          "prioridade": {"type": "string", "enum": ["baixa", "média", "alta"]}
        },
        "required": ["assunto", "prioridade"],
        "additionalProperties": false
      }
    }
  }
}

Como sempre, a resposta fica em choices[0].message.content, como texto contendo o JSON. Faça o parse no seu código.

Se você omitir strict, vale false. Com strict: true, o modelo segue o schema com mais rigor, mas alguns provedores impõem exigências mais rígidas ao próprio schema. Se o provedor recusar seu schema, você recebe 400 invalid_field_value com param response_format.

Quais modelos têm esse recurso

Nem todo modelo domina as duas variantes. Em GET /v1/models, cada modelo indica em capabilities se json_object e json_schema estão como true. Se você escolher um modelo sem esse recurso, a API responde com 400 unsupported_for_model, em vez de entregar texto corrido sem avisar. Assim você percebe o erro na hora, e não só no parse. Como ler as capacidades está em O que um modelo sabe fazer: verificar capacidades, limites, tamanho da saída e profundidade de raciocínio.

No endpoint /responses

Em /responses, você pode usar o mesmo campo response_format. Como alternativa, o endpoint aceita a notação das bibliotecas da OpenAI, text.format, em que o schema fica achatado no objeto:

"text": {
  "format": {"type": "json_schema", "name": "ticket", "strict": true, "schema": { … }}
}

Envie apenas uma das duas notações. A API recusa as duas juntas com HTTP 400, assim como outros campos em text, por exemplo verbosity. Na resposta, o formato escolhido aparece em text.format.

Quando algo não funciona

  • 400 unsupported_for_model: o modelo não tem essa variante. Use outro modelo ou recorra ao json_object.
  • 400 invalid_field_value em response_format: verifique seu schema. Causas comuns são a falta de indicações required ou tipos que o provedor não aceita no modo estrito.
  • A resposta veio cortada e não é JSON válido: normalmente o modelo atingiu o limite de saída. Aumente max_tokens ou reduza a resposta esperada.

Este artigo foi útil?

Voltar para Modelos, limites e erros