Officiële API-documentatie voor Function Calling

Deze interface wordt gebruikt om een chat-completion aan te maken. Door een berichtenlijst en optioneel een lijst met tools (Functions) op te geven, kan het model een tekstueel antwoord genereren, of parameters genereren die voldoen aan een specifieke JSON-structuur om een externe functie aan te roepen.

1. API-informatie

Endpoint: https://api.codingplanx.ai/v1/chat/completions
HTTP-methode: POST
Content-Type: application/json
Authenticatie: Authorization: Bearer {{YOUR_API_KEY}}

2. Aanvraagparameters

2.1 Request Headers

Parameternaam	Type	Verplicht	Voorbeeld	Beschrijving
Content-Type	string	Ja	`application/json`	Vast ingesteld op `application/json`
Accept	string	Ja	`application/json`	Aanbevolen om vast op `application/json` te zetten
Authorization	string	Ja	`Bearer sk-xxxxxx`	Authenticatie met API-sleutel

2.2 Request Body

Parameternaam	Type	Verplicht	Standaardwaarde	Beschrijving
model	string	Ja	-	De model-ID die gebruikt wordt (zoals `gpt-4o`, `gpt-3.5-turbo`, enz.).
messages	array	Ja	-	De lijst met berichten in het gesprek tot nu toe. Elk object bevat `role` ("system", "user", "assistant", "tool") en `content`.
tools	array	Ja	-	De lijst met tools die het model mag aanroepen. Momenteel wordt alleen `type: "function"` ondersteund. Wordt gebruikt om functienaam, beschrijving en parameters te definiëren.
tool_choice	object/str	Nee	`auto`	Bepaalt welke functie het model aanroept. `none`: niet aanroepen; `auto`: automatisch kiezen; `{"type": "function", "function": {"name": "xxx"}}`: dwingt aanroep van een specifieke functie af.
temperature	number	Nee	1	Samplingtemperatuur (0-2). Hoe hoger, hoe willekeuriger; hoe lager, hoe consistenter.
top_p	number	Nee	1	Kans voor nucleus sampling.
n	integer	Nee	1	Het aantal chat-completionkeuzes dat voor elke invoer wordt gegenereerd.
stream	boolean	Nee	false	Of streaming wordt gebruikt. Wanneer ingesteld op `true`, worden tokens verzonden als Server-Sent Events (SSE).
stop	string/array	Nee	null	Stopsequenties waarmee de API stopt met het genereren van tokens.
max_tokens	integer	Nee	inf	Het maximale aantal tokens dat gegenereerd mag worden.
presence_penalty	number	Nee	0	Tussen -2.0 en 2.0. Verhoogt de kans dat het model nieuwe onderwerpen aansnijdt.
frequency_penalty	number	Nee	0	Tussen -2.0 en 2.0. Vermindert de kans dat het model dezelfde inhoud herhaalt.
response_format	object	Nee	-	Specificeert het uitvoerformaat. Bijvoorbeeld `{"type": "json_object"}` om JSON-modus in te schakelen.
seed	integer	Nee	-	Indien opgegeven probeert het systeem zo deterministisch mogelijk te samplen, zodat dezelfde seed en parameters hetzelfde resultaat opleveren.
user	string	Nee	-	Een unieke identifier voor de eindgebruiker, gebruikt voor misbruikmonitoring.

3. Voorbeeldverzoek

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "Hoe is het weer vandaag in Beijing"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Haal het huidige weer op voor een opgegeven locatie",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "Naam van de stad, bijvoorbeeld: Beijing"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

4. Responsparameters

4.1 Structuur van de response body

Parameternaam	Type	Beschrijving
id	string	De unieke identifier van dit verzoek.
object	string	Het objecttype, meestal `chat.completion`.
created	integer	Unix-tijdstempel (seconden).
choices	array	Bevat de lijst met gegenereerde responses.
└ message	object	Bevat `role`, `content` en mogelijk `tool_calls`.
└ finish_reason	string	Reden van stoppen. `stop` (normaal gestopt), `length` (max_tokens bereikt), `tool_calls` (er moet een tool worden aangeroepen).
usage	object	Verbruiksinformatie: `prompt_tokens`, `completion_tokens`, `total_tokens`.

4.2 Voorbeeldresponse (normale tekst)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "In Beijing is het vandaag zonnig, met een temperatuur van 25 graden Celsius."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

5. Veelgestelde vragen (FAQ)

V1: Wat is Function Calling (tool-aanroep)?
A: Dit is een manier om het model externe mogelijkheden te geven. Het model voert zelf geen code uit, maar genereert op basis van jouw beschrijving een JSON-object met de functienaam en de benodigde parameters. Jij moet deze JSON uitlezen, de functie lokaal of op je server uitvoeren, en het resultaat daarna terugsturen naar het model.

V2: Waarom krijg ik geen tool_calls terug, terwijl ik tools heb ingesteld?
A: Mogelijke oorzaken zijn:

Het model vindt dat de vraag van de gebruiker geen tool-aanroep vereist.
De functiebeschrijving (description) is niet duidelijk genoeg, waardoor het model de intentie niet goed kan matchen.
tool_choice is expliciet ingesteld op none.
Beperkingen van het model zelf (aanbevolen wordt om modellen te gebruiken zoals gpt-4o of gpt-3.5-turbo die tool-aanroepen ondersteunen).

V3: Hoe forceer ik dat het model een specifieke functie moet aanroepen?
A: Je kunt tool_choice instellen op een specifiek object, bijvoorbeeld:
"tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}
Op die manier zal het model proberen parameters voor die functie te genereren, zelfs als het denkt dat dit niet nodig is.

V4: Wat moet ik doen als finish_reason gelijk is aan length?
A: Dit betekent dat de gegenereerde response de limiet van max_tokens heeft overschreden of dat de contextlimiet van het model is bereikt. Je kunt proberen max_tokens te verhogen, of de lengte van de messages-geschiedenis te verkorten.

V5: Waar moet ik op letten bij JSON-modus (JSON Mode)?
A: Wanneer je response_format: { "type": "json_object" } instelt, moet je in de System- of User-berichten expliciet aangeven dat het model in JSON-formaat moet antwoorden (bijvoorbeeld met een instructie als “antwoord in JSON-formaat”), anders kan het model in een lus terechtkomen waarin het alleen spaties blijft genereren.

V6: Hoe ga ik om met meerdere tool-aanroepen?
A: In één verzoek kan het model meerdere tool-aanroepen tegelijk genereren (bijvoorbeeld tegelijk het weer in Beijing en Shanghai opvragen). Je moet dan door de array choices[0].message.tool_calls itereren en voor elke aanroep de bijbehorende lokale logica uitvoeren.