API-documentatie: gestructureerde output maken

Beschrijving van de endpoint

Gegeven een prompt retourneert het model een of meer voorspelde aanvullingen, en ondersteunt het het afdwingen van gestructureerde data-uitvoer volgens een opgegeven JSON Schema.

Officiële referentiedocumentatie: OpenAI Structured Outputs

Basisinformatie van de API

• HTTP-methode: POST
• Request-pad: https://api.codingplanx.ai/v1/chat/completions
• Dataformaat: application/json

---

Request-headers (Headers)

---

Request-body (Request Body)

Request-voorbeeld (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Bepaal of de invoer van de gebruiker specifieke richtlijnen schendt en leg uit waarom, indien dat zo is."
    },
    {
      "role": "user",
      "content": "Hoe bereid ik me voor op een sollicitatiegesprek?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Bepaalt of inhoud specifieke moderatieregels schendt",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Geeft aan of de inhoud de richtlijnen schendt"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type overtreding, als de inhoud de richtlijnen schendt. Anders null.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Uitleg waarom de inhoud de richtlijnen schendt"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

Response-body (Response Body)

Response-voorbeeld (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hallo, hoe kan ik u vandaag helpen?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

Veelgestelde vragen (FAQs)

1. Wat is response_format en hoe zorg ik ervoor dat het model strikte JSON-uitvoer geeft?

Met de parameter response_format kunt u vereisen dat het model in een specifiek formaat antwoordt. Als u “gestructureerde output” wilt gebruiken, moet u deze instellen op {"type": "json_schema"} en daarin uw JSON Schema definiëren, met strict: true ingeschakeld. Zo zorgt u ervoor dat het model 100% volgens de door u gedefinieerde velden en datatypen uitvoert, zonder dat u in uw code extra fouttolerante JSON-parsing hoeft toe te passen.

2. Waarom wordt mijn JSON-uitvoer afgekapt?

Als in uw response de waarde van choices[0].finish_reason gelijk is aan length, betekent dit dat de gegenereerde tekst de limiet van max_tokens heeft bereikt, of de maximale contextlengte van het model heeft overschreden. Het wordt aanbevolen om de waarde van max_tokens in uw request te verhogen.

3. Wat is het verschil tussen temperature en top_p? Welke moet ik aanpassen?

Beide parameters worden gebruikt om de willekeurigheid van de modeloutput te regelen:

• temperature schaalt de kansverdeling van de output van het model. Hoe lager de waarde, hoe consistenter en voorspelbaarder de output; hoe hoger de waarde, hoe creatiever en gevarieerder.
• top_p (nucleus sampling) beperkt het model tot woorden/tokens waarvan de gecumuleerde kans p bereikt. Officiële aanbeveling: pas slechts één van beide parameters aan, niet allebei tegelijk.

4. Wat gebeurt er als ik stream: true inschakel?

Als u stream: true instelt, wacht de API niet tot het volledige antwoord is gegenereerd voordat het wordt teruggestuurd. In plaats daarvan wordt de output realtime als een typemachine gestreamd. Het teruggegeven formaat verandert dan naar Server-Sent Events (SSE). De client moet de gegevensstroom uitlezen en delta.content samenvoegen totdat het [DONE]-signaal wordt ontvangen.

5. Hoe zorg ik ervoor dat dezelfde prompt elke keer exact hetzelfde antwoord oplevert?

Hoewel grote taalmodellen een zekere mate van willekeur bevatten, kunt u door een specifieke seen-parameter (seed) mee te geven en temperature op 0 te zetten een zo deterministisch mogelijk resultaat krijgen. Als de system_fingerprint in de response verandert, betekent dit dat de backendconfiguratie van het model is aangepast; in dat geval kunnen zelfs met dezelfde seed kleine verschillen optreden.