Chat Completions API-documentatie

Deze API wordt gebruikt om, gegeven een reeks gespreksberichten, één of meer voorspelde aanvullingen van het model terug te geven. Ondersteunt streaming-uitvoer, tool-calls (Function Calling) en het aanpassen van verschillende sampling-parameters.

1. Interface-informatie

Interfacenaam: Officiële N-test
HTTP-methode: POST
Request-URL: https://api.codingplanx.ai/v1/chat/completions
Content-Type: application/json
Authenticatie: Bearer {{YOUR_API_KEY}}

2. Request-headers (Headers)

Parameternaam	Verplicht	Type	Beschrijving	Voorbeeld
Content-Type	Ja	string	Type media-indeling	`application/json`
Accept	Ja	string	Het responsformaat dat de client accepteert	`application/json`
Authorization	Nee	string	API-toegangstoken	`Bearer sk-xxxxxx`

3. Request-body (Request Body)

Parameternaam	Verplicht	Type	Beschrijving
model	Ja	string	De te gebruiken model-ID (zoals `gpt-4o`, `gpt-3.5-turbo`).
messages	Ja	array	Lijst met gespreksberichten. Elk object bevat `role` (system/user/assistant) en `content`.
tools	Ja	array	Een lijst met tools die het model kan aanroepen. Momenteel worden alleen functies ondersteund.
tool_choice	Ja	object	Bepaalt welke functie het model aanroept. `none` (niet aanroepen), `auto` (automatisch), of een specifiek gekozen functie.
temperature	Nee	number	Sampling-temperatuur (0-2). Hoe hoger, hoe willekeuriger; hoe lager, hoe deterministischer. Aanbevolen om dit of `top_p` aan te passen, niet allebei tegelijk.
top_p	Nee	number	Nucleus sampling. 0.1 betekent dat alleen tokens binnen de bovenste 10% kansmassa worden overwogen.
n	Nee	integer	Standaard is 1. Het aantal antwoorden dat voor elk invoerbericht wordt gegenereerd.
stream	Nee	boolean	Standaard is false. Als dit true is, worden incrementele tokens verzonden zoals in ChatGPT.
stop	Nee	string	Stopsequentie. De generatie stopt wanneer het model deze tekens tegenkomt.
max_tokens	Nee	integer	Het maximale aantal tokens dat wordt gegenereerd. Standaard is inf.
presence_penalty	Nee	number	Tussen -2.0 en 2.0. Straft onderwerpen die al zijn verschenen af en vergroot de kans op nieuwe onderwerpen.
frequency_penalty	Nee	number	Tussen -2.0 en 2.0. Straft herhaalde woorden af.
logit_bias	Nee	object	Past de waarschijnlijkheid van het verschijnen van specifieke tokens aan.
user	Nee	string	Identificatie van de eindgebruiker, gebruikt voor misbruikdetectie.
response_format	Nee	object	Geeft het retourformaat aan. Bijvoorbeeld `{ "type": "json_object" }` om JSON-modus in te schakelen.
seen	Nee	integer	Functie in testfase. Geeft een seed op om deterministische uitvoer te proberen te bereiken.

4. Responsparameters (Response Body)

Parameternaam	Type	Beschrijving
id	string	De unieke identificatie van deze request.
object	string	Objecttype, meestal `chat.completion`.
created	integer	Tijdstempel van het aanmaken van de request (seconden).
choices	array	Lijst met antwoordopties.
├─ index	integer	De index van deze optie in de lijst.
├─ message	object	Het specifieke bericht dat door het model is gegenereerd.
│ ├─ role	string	De rol, meestal `assistant`.
│ └─ content	string	De tekstinhoud van het bericht.
└─ finish_reason	string	De reden waarom de generatie stopte (zoals `stop`, `length`, `tool_calls`).
usage	object	Tokengebruik.
├─ prompt_tokens	integer	Aantal tokens gebruikt voor de invoer.
├─ completion_tokens	integer	Aantal tokens gebruikt voor de uitvoer.
└─ total_tokens	integer	Totaal aantal gebruikte tokens.

5. Voorbeeld (Example)

Voorbeeldrequest

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "wie ben jij?"
        }
    ],
    "n": 1,
    "max_tokens": 100,
    "temperature": 0.8,
    "stream": false
}

Voorbeeldrespons

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

6. Veelgestelde vragen (FAQs)

V: Waarom krijg ik een foutmelding wanneer ik response_format: { "type": "json_object" } instel?
A: Wanneer je JSON-modus gebruikt, moet je in messages expliciet via een system- of user-bericht aangeven dat het model JSON moet genereren (bijvoorbeeld: “Geef antwoord in JSON-formaat”). Anders kan het model vastlopen of een fout geven omdat het geen geldige JSON kan genereren.

V: Kunnen temperature en top_p tegelijkertijd worden aangepast?
A: Technisch gezien wel, maar officieel wordt meestal aangeraden om één van beide te gebruiken. Het aanpassen van één parameter is doorgaans voldoende om de willekeurigheid van de uitvoer te beïnvloeden; beide tegelijk aanpassen kan leiden tot moeilijk voorspelbare resultaten.

V: Hoe ontvang ik gegevens wanneer stream: true is ingesteld?
A: Wanneer streaming is ingeschakeld, stuurt de server een reeks Server-Sent Events (SSE). Het datagedeelte van elk event is een JSON-object, en aan het einde wordt data: [DONE] verzonden. Je moet een streaming-parserbibliotheek gebruiken (zoals Python’s response.iter_lines()) om de gegevens regel voor regel te verwerken.

V: Hoe wordt het tokengebruik berekend?
A: Voor Engels komt 1 token ongeveer overeen met 4 tekens of 0,75 woord; voor Chinees kan 1 karakter overeenkomen met 1-2 tokens. Het daadwerkelijke verbruik is gebaseerd op het veld usage in de respons.

V: Wat betekent finish_reason: "length"?
A: Dit betekent dat de gegenereerde inhoud de limiet overschreed die je in max_tokens hebt ingesteld, of dat de maximale contextlengte van het model is bereikt, waardoor de inhoud is afgekapt.

V: Ondersteunt de interface function calling?
A: Ja. Definieer het functieprototype via de parameter tools; afhankelijk van de behoefte retourneert het model tool_calls in choices[0].message in plaats van normale content.