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 aojson_object.400 invalid_field_valueemresponse_format: verifique seu schema. Causas comuns são a falta de indicaçõesrequiredou 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_tokensou reduza a resposta esperada.