Documentation API : Créer des sorties structurées

Description de l'API

Étant donné un prompt (Invite), le modèle renvoie une ou plusieurs réponses de complétion prédites, et prend en charge le forçage du modèle à générer des données structurées selon un schéma JSON spécifié (JSON Schema).

Documentation officielle de référence : Sorties structurées OpenAI (Structured Outputs)

Informations de base de l'API

• Méthode de requête : POST
• Endpoint de la requête : https://api.codingplanx.ai/v1/chat/completions
• Format des données : application/json

---

En-têtes de requête (Headers)

---

Corps de la requête (Request Body)

Exemple de requête (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Determine if the user input violates specific guidelines and explain if they do."
    },
    {
      "role": "user",
      "content": "How do I prepare for a job interview?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Determines if content is violating specific moderation rules",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Indicates if the content is violating guidelines"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type of violation, if the content is violating guidelines. Null otherwise.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Explanation of why the content is violating"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

Corps de la réponse (Response Body)

Exemple de réponse (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

Foire Aux Questions (FAQ)

1. Qu'est-ce que response_format et comment garantir que le modèle génère du JSON strict ?

Le paramètre response_format vous permet d'exiger que le modèle renvoie les données dans un format spécifique. Si vous souhaitez utiliser les "Sorties structurées", vous devez le définir sur {"type": "json_schema"}, définir votre JSON Schema à l'intérieur, et activer strict: true. Cela garantit que le modèle génère le contenu à 100 % en fonction des champs et des types de données que vous avez définis, éliminant ainsi le besoin de traitement de tolérance aux pannes JSON dans votre code.

2. Pourquoi ma sortie JSON est-elle tronquée ?

Si la valeur de choices[0].finish_reason dans les données de réponse est length, cela signifie que le texte généré a atteint la limite de max_tokens ou a dépassé la limite maximale de longueur de contexte du modèle. Il est recommandé d'augmenter la valeur du paramètre max_tokens dans votre requête.

3. Quelle est la différence entre les paramètres temperature et top_p ? Lequel dois-je ajuster ?

Les deux paramètres sont utilisés pour contrôler l'aléatoire de la sortie du modèle :

• temperature met à l'échelle la distribution de probabilité de sortie du modèle. Plus la valeur est faible, plus la sortie est rigoureuse et déterministe ; plus la valeur est élevée, plus la sortie est divergente et créative.
• top_p (échantillonnage de noyau) restreint le modèle à choisir uniquement parmi le vocabulaire le plus fréquent dont la probabilité cumulée atteint p. Recommandation officielle : N'ajustez qu'un seul de ces paramètres à la fois. Ne modifiez pas simultanément temperature et top_p.

4. Que se passe-t-il si j'active stream: true ?

Lorsque vous définissez stream: true, l'API n'attendra pas que l'intégralité de la réponse soit générée avant de la renvoyer. Au lieu de cela, elle renverra des fragments de données en temps réel (streaming), comme une machine à écrire. Le format des données renvoyées deviendra des Server-Sent Events (SSE). Le client doit écouter le flux de données pour concaténer delta.content jusqu'à ce qu'il reçoive la balise [DONE] indiquant la fin.

5. Comment s'assurer que l'appel du même Prompt donne exactement la même réponse à chaque fois ?

Bien que les grands modèles de langage aient une nature aléatoire, vous pouvez obtenir une sortie hautement déterministe en transmettant un paramètre seen (Seed) spécifique et en définissant la temperature à 0. Si vous remarquez que le system_fingerprint dans la réponse change, cela signifie qu'il y a eu un ajustement mineur dans la configuration du modèle en arrière-plan. Dans ce cas, même avec le même Seed, de légères différences dans les résultats peuvent apparaître.