De inspanningsgraad van reasoning-modellen regelen (Chat Completions)

API-beschrijving

Gegeven een prompt retourneert dit model één of meerdere voorspelde completion-antwoorden (met ondersteuning voor het regelen van de denkinspanning van reasoning-modellen).

Officiële documentatie: OpenAI Reasoning Guides
API-status: vrijgegeven (released)

Verzoekbeschrijving

Methode: POST
Endpoint: https://api.codingplanx.ai/v1/chat/completions

Requestheaders (Headers)

Parameternaam	Verplicht	Type	Voorbeeldwaarde	Beschrijving
`Content-Type`	Ja	`string`	`application/json`	Gegevensformaat
`Accept`	Ja	`string`	`application/json`	Verwacht antwoordformaat
`Authorization`	Nee	`string`	`Bearer {{YOUR_API_KEY}}`	Verificatiegegevens

Parameters van de requestbody (Body)

Gegevensformaat: application/json

Parameternaam	Verplicht	Type	Beschrijving
`model`	Ja	`string`	De ID van het model dat gebruikt moet worden (bijvoorbeeld `o4-mini`).
`messages`	Ja	`array`	De lijst met berichten die tot nu toe in het gesprek voorkomen. Bevat `role` (zoals user/assistant) en `content` (berichtinhoud).
`tools`	Ja	`array`	Een lijst met tools (functies) die het model kan aanroepen. Wordt gebruikt om functies aan te bieden waarvoor het model JSON-invoer kan genereren.
`tool_choice`	Ja	`object`	Bepaalt welke functie het model moet aanroepen. `none` betekent niet aanroepen, `auto` betekent automatisch kiezen.
`reasoning_effort`	Nee	`string`	Kernparameter: regelt hoeveel inspanning (denkdiepte) het reasoning-model gebruikt bij het genereren van een antwoord. Veelgebruikte waarden zijn `low`, `medium`, `high`.
`temperature`	Nee	`number`	Sampling-temperatuur, tussen 0 en 2. Hogere waarden (zoals 0.8) maken de output willekeuriger; lagere waarden (zoals 0.2) maken deze meer gefocust en deterministisch. Aanbevolen wordt om slechts één van `temperature` of `top_p` aan te passen.
`top_p`	Nee	`number`	Nucleus sampling. `0.1` betekent dat alleen tokens worden overwogen die samen de bovenste 10% kansmassa vormen. Aanbevolen wordt om slechts één van `temperature` of `top_p` aan te passen.
`n`	Nee	`integer`	Standaard is 1. Hoeveel chat completion-keuzes per invoerbericht moeten worden gegenereerd.
`stream`	Nee	`boolean`	Standaard is false. Indien ingesteld op true, worden gedeeltelijke berichtincrementen verzonden via Server-Sent Events (SSE), en eindigt de stream met `data: [DONE]`.
`stop`	Nee	`string`	Maximaal 4 tekenreeksen waarop de API stopt met verdere token-generatie.
`max_tokens`	Nee	`integer`	Het maximale aantal tokens dat in de chat completion mag worden gegenereerd. De totale lengte van invoer plus gegenereerde tokens is beperkt door de contextlengte van het model.
`presence_penalty`	Nee	`number`	Een getal tussen -2.0 en 2.0. Positieve waarden bestraffen tokens op basis van het al dan niet eerder voorkomen ervan, waardoor de kans toeneemt dat over nieuwe onderwerpen wordt gesproken.
`frequency_penalty`	Nee	`number`	Een getal tussen -2.0 en 2.0. Positieve waarden bestraffen tokens op basis van hun huidige frequentie in de tekst, waardoor herhaling wordt verminderd.
`logit_bias`	Nee	`object`	Accepteert een JSON-object dat token-ID's koppelt aan bias-waarden (-100 tot 100), om de kans te beïnvloeden dat bepaalde tokens in de completion verschijnen.
`user`	Nee	`string`	Een unieke identifier voor de eindgebruiker, om monitoring en misbruikdetectie te ondersteunen.
`response_format`	Nee	`object`	Geeft het verplichte uitvoerformaat van het model aan. Bijvoorbeeld `{"type": "json_object"}` schakelt de JSON-modus in.
`seen`	Nee	`integer`	Functionaliteit in testfase (vergelijkbaar met seed). Indien opgegeven, probeert het systeem zo deterministisch mogelijk te samplen, zodat dezelfde parameters dezelfde resultaten opleveren.

Voorbeeldrequest

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Hallo, kun je het principe van quantumcomputing gedetailleerd uitleggen?"
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

Antwoordbeschrijving

Parameters van de responsebody

Gegevensformaat: application/json

Parameternaam	Type	Beschrijving
`id`	`string`	De unieke identifier van deze aanvraag.
`object`	`string`	Het objecttype, meestal `chat.completion`.
`created`	`integer`	Tijdstempel van aanmaak.
`choices`	`array`	Lijst met completion-resultaten.
└ `index`	`integer`	De index van deze keuze in de lijst.
└ `message`	`object`	Het door het model gegenereerde antwoordbericht. Bevat `role` en `content`.
└ `finish_reason`	`string`	De reden waarom de generatie is gestopt (bijvoorbeeld `stop`, `length`).
`usage`	`object`	Statistieken over tokenverbruik.
└ `prompt_tokens`	`integer`	Het aantal tokens dat door de prompt is verbruikt.
└ `completion_tokens`	`integer`	Het aantal tokens dat door de gegenereerde output is verbruikt.
└ `total_tokens`	`integer`	Het totale aantal tokens.

Voorbeeldresponse (HTTP 200 OK)

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

FAQ (Veelgestelde vragen)

1. Wat doet de parameter `reasoning_effort`?

reasoning_effort wordt gebruikt om te bepalen hoeveel rekenkracht en tijd een model met geavanceerde reasoning-capaciteiten (zoals modellen uit de o1/o4-serie van OpenAI) besteedt aan intern nadenken voordat het een definitief antwoord geeft. Meestal worden drie niveaus ondersteund: low, medium en high. Wanneer ingesteld op high, voert het model diepgaandere logische afleidingen uit, wat geschikt is voor complexe wiskundige of programmeervraagstukken; de responstijd zal dan doorgaans ook toenemen.

2. Waarom ontvang ik geen standaard JSON-response wanneer `stream: true` is ingeschakeld?

Wanneer streaming (stream: true) is ingeschakeld, gebruikt de API het Server-Sent Events (SSE)-protocol om continu datablocks (chunks) terug te sturen. Elk blok wordt verzonden in de vorm data: {...}. Zodra alle inhoud is overgedragen, wordt een laatste bericht data: [DONE] verzonden. Ontwikkelaars moeten de stream regel voor regel uitlezen en de JSON-string na data: parseren om het volledige antwoord samen te stellen.

3. Waarom wordt aangeraden om slechts één van `temperature` en `top_p` aan te passen?

Deze twee parameters sturen allebei de willekeur en diversiteit van de modeloutput. temperature verandert de kansverdeling door logits te schalen, terwijl top_p (nucleus sampling) de kandidatenpool beperkt door tokens met lage cumulatieve waarschijnlijkheid uit te sluiten. Als beide tegelijk worden aangepast, wordt het gedrag van het model moeilijker te voorspellen en te beheersen. Daarom is het best practice om er één vast te laten staan (meestal op de standaardwaarde) en alleen de andere aan te passen.

4. Wat betekent het als `finish_reason` `"length"` teruggeeft?

Dit betekent dat het antwoord van het model voortijdig is afgebroken. Daar zijn meestal twee mogelijke oorzaken voor: ten eerste kan het aantal gegenereerde tokens de in de request ingestelde limiet max_tokens hebben bereikt; ten tweede kan de som van prompt en gegenereerde output groter zijn dan het maximale contextvenster van het model. In dat geval wordt aanbevolen om de gespreksgeschiedenis in te korten of max_tokens te verhogen.

5. Hoe dwing ik het model om JSON terug te geven?

Je kunt de JSON-modus inschakelen door "response_format": {"type": "json_object"} mee te sturen in de requestbody. Zeer belangrijk: wanneer deze modus is ingeschakeld, moet je in messages (meestal in een system- of user-prompt) ook expliciet in natuurlijke taal aangeven dat het model JSON moet retourneren. Anders kan het model in een oneindige lus van witruimtes terechtkomen totdat de tokenlimiet is bereikt.