Sorties Structurees (Structured Outputs)

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.

Protocole	Parametre	Modeles compatibles
OpenAI Chat `/v1/chat/completions`	`response_format.type: "json_schema"`	Claude 4.5+, GPT-4o / GPT-5 et successeurs, serie Gemini
Anthropic Messages `/v1/messages`	`output_config.format.type: "json_schema"`	Claude 4.5+ (direct / Vertex / Bedrock)
OpenAI Responses `/v1/responses`	`text.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

Caracteristique	Protocole OpenAI	Protocole Anthropic
Champ `name`	Obligatoire	Non pris en charge (gere automatiquement par la passerelle lors des appels inter-protocoles)
Champ `strict`	Optionnel, `true` recommande	Non pris en charge
Contraintes numeriques (`minimum`, `maximum`, etc.)	Prises en charge	Non prises en charge (nettoyees automatiquement par la passerelle, sans impact sur la requete)
Contraintes de chaine (`minLength`, `maxLength`)	Prises en charge	Non 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>

reason	Signification
`model_unsupported`	Ce modele (ou ce modele sur la plateforme actuelle) ne prend pas en charge les sorties structurees
`json_object_unsupported_on_anthropic`	Le mode `json_object` ne peut pas etre converti au format Anthropic
`json_schema_missing_schema`	Le type `json_schema` a ete specifie mais le champ `schema` est manquant
`schema_keywords_stripped`	Certains 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 sortie	Correspondance stricte avec le Schema specifie	Garantit uniquement un JSON valide
Controle des champs	Noms, types et caractere obligatoire des champs sont contraints	Aucune contrainte
Protocoles compatibles	OpenAI / Anthropic / Responses	Protocole compatible OpenAI uniquement
Support Claude	Via `output_config.format`	Non 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

Quels modeles prennent en charge les Structured Outputs ?

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.

Le JSON Schema est-il modifie lors d'appels inter-protocoles ?

Oui. Lorsque vous appelez un modele Claude via le protocole OpenAI, la passerelle effectue automatiquement :

La conversion de response_format en output_config.format
La suppression des mots-cles du Schema non pris en charge par Anthropic (minimum, maxLength, etc.)
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.

Les Structured Outputs peuvent-ils etre utilises simultanement avec Extended Thinking ?

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"
  }
}

Quelle est la difference du mecanisme de degradation par rapport a d'autres plateformes d'agregation comme OpenRouter ?

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.

Démarrage

Fonctionnalités passerelle

Capacités des modèles

Référence du protocole

Gestion de la plateforme

Confidentialité et conditions

Sorties Structurees (Structured Outputs)

Apercu des capacites

Correspondance des parametres par protocole

Demarrage rapide

Protocole OpenAI (recommande)

Utilisation d’autres modeles (exemple GLM-5.2)

Protocole natif Claude

Points cles pour la redaction du Schema

Champs obligatoires

Objets imbriques

Differences de Schema entre protocoles

Mecanisme de degradation automatique

En-tetes de reponse

Exemple de detection

Difference avec le mode `json_object`

Questions frequentes

​Apercu des capacites

​Correspondance des parametres par protocole

​Demarrage rapide

​Protocole OpenAI (recommande)

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

​Protocole natif Claude

​Points cles pour la redaction du Schema

​Champs obligatoires

​Objets imbriques

​Differences de Schema entre protocoles

​Mecanisme de degradation automatique

​En-tetes de reponse

​Exemple de detection

​Difference avec le mode json_object

​Questions frequentes

Apercu des capacites

Correspondance des parametres par protocole

Demarrage rapide

Protocole OpenAI (recommande)

Utilisation d’autres modeles (exemple GLM-5.2)

Protocole natif Claude

Points cles pour la redaction du Schema

Champs obligatoires

Objets imbriques

Differences de Schema entre protocoles

Mecanisme de degradation automatique

En-tetes de reponse

Exemple de detection

Difference avec le mode `json_object`

Questions frequentes