Saltar para o conteúdo principal

​
Visão geral das capacidades

Saídas Estruturadas (Structured Outputs) fazem com que a resposta do modelo siga rigorosamente o JSON Schema que você definiu, garantindo que o valor retornado possa ser analisado diretamente pelo seu programa, sem necessidade de expressões regulares ou pós-processamento. Diferente de pedir ao modelo no prompt para “retornar JSON”, as saídas estruturadas são baseadas em decodificação restrita (Constrained Decoding): o provedor compila o JSON Schema em regras gramaticais e restringe a geração token a token durante a inferência, tornando impossível que o modelo produza conteúdo que viole o Schema. Cenários típicos:
  • Extrair entidades e campos de texto não estruturado
  • Classificação / rotulagem / análise de sentimento
  • Padronização de resultados intermediários em raciocínio multi-etapas
  • Restrição de tipos fortes nos parâmetros de chamada de ferramentas de Agents

​
Comparação de parâmetros por protocolo

Os nomes dos parâmetros diferem entre os três protocolos, mas o mecanismo subjacente é o mesmo: a saída do modelo corresponde rigorosamente ao JSON Schema que você forneceu.
ProtocoloParâmetroModelos compatíveis
OpenAI Chat /v1/chat/completionsresponse_format.type: "json_schema"Claude 4.5+, GPT-4o / série GPT-5, série Gemini
Anthropic Messages /v1/messagesoutput_config.format.type: "json_schema"Claude 4.5+ (direto / Vertex); Bedrock apenas 4.5–4.6
OpenAI Responses /v1/responsestext.format.type: "json_schema"Conforme capacidade do modelo upstream

​
Limitações do AWS Bedrock

No AWS Bedrock, as versões Claude 4.7 e superiores utilizam o caminho de inferência Mantle, que atualmente não suporta output_config.format. O gateway remove automaticamente o campo format para esses modelos e marca a degradação no cabeçalho de resposta (veja Mecanismo de degradação automática abaixo). A requisição não retornará erro por causa disso.

​
Início rápido

​
Protocolo OpenAI (recomendado)

Aplicável a todos os modelos que suportam saídas estruturadas, universal entre fornecedores. 
from openai import OpenAI

client = OpenAI(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "user", "content": "Extraia as seguintes informações: João Silva, 28 anos, Centro de São Paulo"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.choices[0].message.content)
print(data)
# {"name": "João Silva", "age": 28, "city": "Centro de São Paulo"}

​
Usando outros modelos (exemplo GLM-5.2)

O mesmo conjunto de parâmetros do protocolo OpenAI se aplica a todos os modelos que suportam saídas estruturadas. Basta trocar o model.
Python
from openai import OpenAI

client = OpenAI(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com/v1",
)

response = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "user", "content": "Extraia as seguintes informações: João Silva, 28 anos, Centro de São Paulo"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.choices[0].message.content)
print(data)
# {"name": "João Silva", "age": 28, "city": "Centro de São Paulo"}

​
Protocolo nativo Claude

Usando o SDK da Anthropic diretamente, com o parâmetro output_config.format. 
import anthropic

client = anthropic.Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com",
)

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Extraia as seguintes informações: João Silva, 28 anos, Centro de São Paulo"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.content[0].text)
print(data)

​
Pontos-chave para escrever o Schema

​
Campos obrigatórios

Todos os tipos object devem declarar explicitamente additionalProperties: false, caso contrário alguns provedores upstream rejeitarão a requisição. 
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "score": { "type": "number" }
  },
  "required": ["name", "score"],
  "additionalProperties": false
}

​
Objetos aninhados

Objetos object aninhados também precisam de additionalProperties: false: 
{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["name", "email"],
      "additionalProperties": false
    }
  },
  "required": ["user"],
  "additionalProperties": false
}

​
Diferenças de Schema entre protocolos

CaracterísticaProtocolo OpenAIProtocolo Anthropic
Campo nameObrigatórioNão suportado (tratado automaticamente pelo gateway em chamadas entre protocolos)
Campo strictOpcional, recomendado trueNão suportado
Restrições numéricas (minimum, maximum etc.)SuportadoNão suportado (o gateway limpa automaticamente, sem afetar a requisição)
Restrições de string (minLength, maxLength)SuportadoNão suportado (o gateway limpa automaticamente)
Ao chamar modelos Claude usando o protocolo OpenAI, o gateway converte automaticamente o formato do Schema e limpa palavras-chave incompatíveis, sem necessidade de adaptação manual.

​
Mecanismo de degradação automática

O gateway habilita por padrão a proteção de degradação automática de saídas estruturadas para todas as requisições. Quando o modelo ou a plataforma não oferece suporte, o gateway não retorna um erro, mas remove automaticamente a restrição do Schema e marca o motivo da degradação no cabeçalho de resposta. Sua requisição ainda receberá uma resposta normal do modelo, apenas a saída não será restringida pelo Schema. Isso significa que você pode ativar saídas estruturadas de forma unificada no cliente sem precisar fazer verificações de compatibilidade para cada modelo:
  • Troca de modelos sem preocupação: o mesmo código funciona ao alternar entre Claude, GPT, Gemini e GLM. Mesmo que o modelo de destino não suporte saídas estruturadas, a requisição não falhará
  • Roteamento de fallback transparente: quando o canal principal não está disponível e o fallback roteia para um canal de backup, mesmo que a versão do modelo do canal de backup não suporte saídas estruturadas, a requisição ainda será concluída normalmente
  • Lógica simplificada no cliente: não é necessário manter uma lista de “quais modelos suportam saídas estruturadas”. O gateway já cuida disso automaticamente; o cliente só precisa verificar o cabeçalho de resposta para decidir se é necessária uma análise adicional

​
Cabeçalho de resposta

X-Structured-Output-Degraded: <reason>
reasonSignificado
model_unsupportedEste modelo (ou este modelo na plataforma atual) não suporta saídas estruturadas
json_object_unsupported_on_anthropicO modo json_object não pode ser convertido para o formato Anthropic
json_schema_missing_schemaO tipo json_schema foi especificado, mas o campo schema está ausente
schema_keywords_strippedAlgumas palavras-chave de restrição do Schema foram removidas (como minimum, maxLength)

​
Exemplo de detecção

Python
import httpx

response = httpx.post(
    "https://aihubmix.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer <AIHUBMIX_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "claude-sonnet-5",
        "messages": [{"role": "user", "content": "Extraia as informações: João Silva, 28 anos"}],
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "person",
                "strict": True,
                "schema": {
                    "type": "object",
                    "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                    "required": ["name", "age"],
                    "additionalProperties": False,
                }
            }
        }
    }
)

# Verifica se ocorreu degradação (por exemplo, quando a requisição foi roteada para um canal Bedrock sem suporte)
degraded = response.headers.get("X-Structured-Output-Degraded")
if degraded:
    print(f"Saída estruturada degradada: {degraded}")
    # Neste caso, a resposta do modelo ainda é normal, mas a saída não é restringida pelo Schema
else:
    import json
    data = json.loads(response.json()["choices"][0]["message"]["content"])
    print(data)  # {"name": "João Silva", "age": 28}

​
Diferença em relação ao modo json_object

json_schema (Saídas Estruturadas)json_object
Garantia de saídaCorrespondência rigorosa com o Schema especificadoApenas garante que é um JSON válido
Controle de camposNomes, tipos e obrigatoriedade dos campos são restritosSem restrições
Protocolos compatíveisOpenAI / Anthropic / ResponsesApenas protocolos compatíveis com OpenAI
Suporte ClaudeVia output_config.formatNão suportado
O modo json_object não pode ser convertido para o protocolo nativo Claude. Se você enviar response_format: {"type": "json_object"} para o Claude via protocolo OpenAI, o cabeçalho de resposta marcará a degradação json_object_unsupported_on_anthropic. Recomenda-se usar diretamente o tipo json_schema.

​
Perguntas frequentes

Série Claude (via output_config.format da API Anthropic):
  • Opus / Sonnet / Haiku 4.5 e versões superiores
  • Fable / Mythos 5 e versões superiores
  • Plataforma Bedrock apenas 4.5–4.6; Vertex AI igual ao acesso direto
Série OpenAI (via response_format):
  • GPT-4o e superiores, série GPT-5
Série Gemini (via responseSchema):
  • Gemini 2.5 e superiores
Você pode verificar as tags de capacidade de cada modelo na página de lista de modelos.
No AWS Bedrock, o Claude 4.7+ utiliza o novo caminho de inferência Mantle, que atualmente não aceita o parâmetro output_config.format. O gateway trata isso automaticamente: remove o campo format e retorna a resposta normalmente, ao mesmo tempo marcando o cabeçalho de degradação X-Structured-Output-Degraded: model_unsupported. O Claude 4.5–4.6 tem suporte completo no Bedrock.
Sim. Ao chamar modelos Claude via protocolo OpenAI, o gateway automaticamente:
  1. Converte response_format para output_config.format
  2. Remove palavras-chave do Schema não suportadas pela Anthropic (minimum, maxLength etc.)
  3. Se alguma palavra-chave for removida, o cabeçalho de resposta marca schema_keywords_stripped
A conversão reversa (protocolo Claude chamando modelos OpenAI) também é automática.
Sim. O format em output_config (saídas estruturadas) e o effort em reasoning (intensidade de raciocínio) são parâmetros independentes e podem ser definidos simultaneamente:
{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": { ... }
    }
  },
  "reasoning": {
    "effort": "high"
  }
}
A maioria das plataformas de agregação de API retorna um erro diretamente quando o modelo não suporta saídas estruturadas. O AIHubMix adota uma estratégia de degradação graciosa: remove automaticamente os parâmetros incompatíveis, retorna a resposta do modelo normalmente e informa o cliente sobre o motivo da degradação através do cabeçalho de resposta X-Structured-Output-Degraded. Sua aplicação não será interrompida por causa disso.