Passer au contenu principal

​
Apercu des capacites

Les sorties structurees (Structured Outputs) permettent a la reponse du modele de respecter strictement un JSON Schema que vous definissez, garantissant que la valeur retournee peut etre directement analysee par votre programme, sans regex ni post-traitement. Contrairement a une simple instruction dans le prompt demandant au modele de “retourner du JSON”, les sorties structurees reposent sur le decodage contraint (Constrained Decoding) : le fournisseur en amont compile le JSON Schema en regles grammaticales qui contraignent la generation token par token lors de l’inference — le modele ne peut pas produire de contenu violant le Schema. Cas d’usage typiques :
  • Extraction d’entites et de champs a partir de texte non structure
  • Classification / etiquetage / analyse de sentiments
  • Transmission standardisee de resultats intermediaires dans un raisonnement multi-etapes
  • Contraintes de typage fort sur les parametres d’appel d’outils d’un Agent

​
Correspondance des parametres par protocole

Les noms de parametres different selon les trois protocoles, mais le mecanisme sous-jacent est identique : la sortie du modele correspond strictement au JSON Schema que vous fournissez.
ProtocoleParametreModeles compatibles
OpenAI Chat /v1/chat/completionsresponse_format.type: "json_schema"Claude 4.5+, GPT-4o / GPT-5 et successeurs, serie Gemini
Anthropic Messages /v1/messagesoutput_config.format.type: "json_schema"Claude 4.5+ (direct / Vertex / Bedrock)
OpenAI Responses /v1/responsestext.format.type: "json_schema"Selon les capacites du modele en amont

​
Demarrage rapide

​
Protocole OpenAI (recommande)

Compatible avec tous les modeles prenant en charge les sorties structurees, universel entre fournisseurs. 
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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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": "John Smith", "age": 28, "city": "San Francisco"}

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<AIHUBMIX_API_KEY>",
  baseURL: "https://aihubmix.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "user", content: "Extract the following information: John Smith, 28 years old, San Francisco" },
  ],
  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,
      },
    },
  },
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data);

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    "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
        }
      }
    }
  }'

​
Utilisation d’autres modeles (exemple GLM-5.2)

Le meme jeu de parametres du protocole OpenAI s’applique a tous les modeles prenant en charge les sorties structurees — il suffit de changer le champ 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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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": "John Smith", "age": 28, "city": "San Francisco"}

​
Protocole natif Claude

Utilisation directe via le SDK Anthropic, avec le parametre 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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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)

curl https://aihubmix.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <AIHUBMIX_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    "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
        }
      }
    }
  }'

​
Points cles pour la redaction du Schema

​
Champs obligatoires

Tout type object doit declarer explicitement additionalProperties: false, sinon certains fournisseurs en amont rejetteront la requete. 
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "score": { "type": "number" }
  },
  "required": ["name", "score"],
  "additionalProperties": false
}

​
Objets imbriques

Les object imbriques necessitent egalement additionalProperties: false : 
{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["name", "email"],
      "additionalProperties": false
    }
  },
  "required": ["user"],
  "additionalProperties": false
}

​
Differences de Schema entre protocoles

CaracteristiqueProtocole OpenAIProtocole Anthropic
Champ nameObligatoireNon pris en charge (gere automatiquement par la passerelle lors des appels inter-protocoles)
Champ strictOptionnel, true recommandeNon pris en charge
Contraintes numeriques (minimum, maximum, etc.)Prises en chargeNon prises en charge (nettoyees automatiquement par la passerelle, sans impact sur la requete)
Contraintes de chaine (minLength, maxLength)Prises en chargeNon prises en charge (nettoyees automatiquement par la passerelle)
Lorsque vous appelez un modele Claude via le protocole OpenAI, la passerelle convertit automatiquement le format du Schema et nettoie les mots-cles incompatibles — aucune adaptation manuelle n’est necessaire.

​
Mecanisme de degradation automatique

Par defaut, la passerelle active la protection par degradation automatique des sorties structurees pour toutes les requetes. Lorsqu’un modele ou une plateforme ne prend pas en charge cette fonctionnalite, la passerelle ne renvoie pas d’erreur mais supprime automatiquement les contraintes de Schema et signale la raison de la degradation dans un en-tete de reponse. Votre requete recevra toujours une reponse normale du modele, mais la sortie ne sera pas soumise aux contraintes strictes du Schema. Cela signifie que vous pouvez activer les sorties structurees de maniere uniforme cote client sans avoir a gerer la compatibilite pour chaque modele :
  • Changement de modele sans souci : lorsque le meme code bascule entre Claude, GPT, Gemini et GLM, meme si le modele cible ne prend pas en charge les sorties structurees, la requete ne provoquera pas d’erreur
  • Repli transparent : Même si la version du modèle qui traite finalement votre requête ne prend pas en charge les sorties structurées, la requête aboutit normalement, la dégradation étant signalée dans l’en-tête de réponse
  • Logique client simplifiee : inutile de maintenir une liste des modeles compatibles avec les sorties structurees, la passerelle gere tout automatiquement ; le client n’a qu’a verifier l’en-tete de reponse pour decider si une analyse supplementaire est necessaire

​
En-tetes de reponse

X-Structured-Output-Degraded: <reason>
reasonSignification
model_unsupportedCe modele (ou ce modele sur la plateforme actuelle) ne prend pas en charge les sorties structurees
json_object_unsupported_on_anthropicLe mode json_object ne peut pas etre converti au format Anthropic
json_schema_missing_schemaLe type json_schema a ete specifie mais le champ schema est manquant
schema_keywords_strippedCertains mots-cles de contrainte du Schema ont ete nettoyes (par ex. minimum, maxLength)

​
Exemple de detection

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": "Extract info: John Smith, 28 years old"}],
        "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,
                }
            }
        }
    }
)

# Verifier si une degradation a eu lieu
degraded = response.headers.get("X-Structured-Output-Degraded")
if degraded:
    print(f"Sortie structuree degradee : {degraded}")
    # La reponse du modele est toujours normale, mais la sortie n'est pas contrainte par le Schema
else:
    import json
    data = json.loads(response.json()["choices"][0]["message"]["content"])
    print(data)  # {"name": "John Smith", "age": 28}

​
Difference avec le mode json_object

json_schema (Sorties structurees)json_object
Garantie de sortieCorrespondance stricte avec le Schema specifieGarantit uniquement un JSON valide
Controle des champsNoms, types et caractere obligatoire des champs sont contraintsAucune contrainte
Protocoles compatiblesOpenAI / Anthropic / ResponsesProtocole compatible OpenAI uniquement
Support ClaudeVia output_config.formatNon pris en charge
Le mode json_object ne peut pas etre converti vers le protocole natif Claude. Si vous envoyez response_format: {"type": "json_object"} a Claude via le protocole OpenAI, l’en-tete de reponse signalera une degradation json_object_unsupported_on_anthropic. Il est recommande d’utiliser directement le type json_schema.

​
Questions frequentes

Serie Claude (via output_config.format de l’API Anthropic) :
  • Opus / Sonnet / Haiku 4.5 et versions ulterieures
  • Fable / Mythos 5 et versions ulterieures
Serie OpenAI (via response_format) :
  • GPT-4o et versions ulterieures, serie GPT-5
Serie Gemini (via responseSchema) :
  • Gemini 2.5 et versions ulterieures
Vous pouvez consulter les etiquettes de capacites de chaque modele sur la page de liste des modeles.
Oui. Lorsque vous appelez un modele Claude via le protocole OpenAI, la passerelle effectue automatiquement :
  1. La conversion de response_format en output_config.format
  2. La suppression des mots-cles du Schema non pris en charge par Anthropic (minimum, maxLength, etc.)
  3. Si des mots-cles ont ete nettoyes, l’en-tete de reponse signale schema_keywords_stripped
La conversion inverse (protocole Claude vers modele OpenAI) est egalement automatique.
Oui. Le champ format (sorties structurees) dans output_config et le champ effort (intensite de reflexion) dans reasoning sont des parametres independants qui peuvent etre definis simultanement :
{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": { ... }
    }
  },
  "reasoning": {
    "effort": "high"
  }
}
La plupart des plateformes d’agregation d’API renvoient directement une erreur lorsqu’un modele ne prend pas en charge les sorties structurees. AIHubMix adopte une strategie de degradation gracieuse : suppression automatique des parametres incompatibles, retour normal de la reponse du modele, et notification au client de la raison de la degradation via l’en-tete X-Structured-Output-Degraded. Votre application ne sera pas interrompue.