Chat Completions

Overzicht

Het Chat Completions-endpoint is de meest gebruikte API voor interactie met grote taalmodellen. Het accepteert een gesprek dat uit meerdere berichten bestaat en retourneert het antwoord van het model. CometAPI routeert dit endpoint naar meerdere providers — waaronder OpenAI, Anthropic Claude (via een compatibiliteitslaag), Google Gemini en andere — via één uniforme interface. Je kunt tussen modellen wisselen door simpelweg de parameter model te wijzigen.

Dit endpoint volgt het OpenAI Chat Completions-formaat. De meeste OpenAI-compatibele SDK’s en tools werken met CometAPI door de base_url te wijzigen naar https://api.cometapi.com/v1.

Belangrijke opmerkingen

Modelspecifiek gedrag — Verschillende modellen kunnen verschillende subsets van parameters ondersteunen en licht afwijkende responsevelden retourneren. Bijvoorbeeld, reasoning_effort is alleen van toepassing op reasoning-modellen (o-series, GPT-5.1+), en sommige modellen ondersteunen mogelijk logprobs of n > 1 niet.

Response-doorgifte — CometAPI geeft modelresponses ongewijzigd door (behalve voor formaatnormalisatie bij routering tussen providers), zodat je output ontvangt die overeenkomt met de oorspronkelijke API.

OpenAI Pro-modellen — Gebruik voor OpenAI Pro-seriemodellen (bijv. o1-pro) in plaats daarvan het endpoint responses.

Berichtrollen

Role	Description
`system`	Stelt het gedrag en de persoonlijkheid van de assistant in. Wordt aan het begin van het gesprek geplaatst.
`developer`	Vervangt `system` voor nieuwere modellen (o1+). Geeft instructies die het model moet volgen, ongeacht de input van de gebruiker.
`user`	Berichten van de eindgebruiker.
`assistant`	Eerdere modelantwoorden, gebruikt om de gespreksgeschiedenis te behouden.
`tool`	Resultaten van tool-/function-calls. Moet `tool_call_id` bevatten dat overeenkomt met de oorspronkelijke tool call.

Voor nieuwere modellen (GPT-4.1, GPT-5 series, o-series) heeft developer de voorkeur boven system voor instructieberichten. Beide werken, maar developer zorgt voor sterker instructievolgend gedrag.

Multimodal Input

Veel modellen ondersteunen afbeeldingen en audio naast tekst. Gebruik het arrayformaat voor content om multimodale berichten te versturen:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this image"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    }
  ]
}

De parameter detail bepaalt de diepgang van de afbeeldingsanalyse:

low — sneller, gebruikt minder tokens (vaste kosten)
high — gedetailleerde analyse, meer tokens verbruikt
auto — het model beslist (standaard)

Streaming

Wanneer stream is ingesteld op true, wordt de response geleverd als Server-Sent Events (SSE). Elke event bevat een chat.completion.chunk-object met incrementele content:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Om Token-gebruiksstatistieken op te nemen in streaming responses, stel je stream_options.include_usage in op true. De usage-data verschijnt in de laatste chunk vóór [DONE].

Structured Outputs

Dwing het model om geldige JSON terug te geven die overeenkomt met een specifiek schema met response_format:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        },
        "required": ["answer", "confidence"],
        "additionalProperties": false
      }
    }
  }
}

JSON Schema mode (json_schema) garandeert dat de output exact overeenkomt met je schema. JSON Object mode (json_object) garandeert alleen geldige JSON — de structuur wordt niet afgedwongen.

Tool / Function Calling

Schakel het model in om externe functies aan te roepen door tooldefinities op te geven:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Wanneer het model besluit een tool aan te roepen, heeft de response finish_reason: "tool_calls" en bevat de array message.tool_calls de functienaam en argumenten. Vervolgens voer je de functie uit en stuur je het resultaat terug als een tool-bericht met de overeenkomende tool_call_id.

Response Fields

Veld	Beschrijving
`id`	Unieke completion-identificatie (bijv. `chatcmpl-abc123`).
`object`	Altijd `chat.completion`.
`model`	Het model dat de response heeft gegenereerd (kan een versiesuffix bevatten).
`choices`	Array met completion-keuzes (meestal 1, tenzij `n` > 1).
`choices[].message`	Het responsebericht van de assistant met `role`, `content` en optioneel `tool_calls`.
`choices[].finish_reason`	Waarom het model stopte: `stop`, `length`, `tool_calls` of `content_filter`.
`usage`	Uitsplitsing van Token-verbruik: `prompt_tokens`, `completion_tokens`, `total_tokens` en gedetailleerde subaantallen.
`system_fingerprint`	Fingerprint van de backendconfiguratie voor debuggen van reproduceerbaarheid.

Opmerkingen over providers heen

Parameterondersteuning bij verschillende providers

Parameter	OpenAI GPT	Claude (via compat)	Gemini (via compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	alleen 1	1–8
`stop`	Tot 4	Tot 4	Tot 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (gebruik `thinking` voor Gemini native)

max_tokens vs max_completion_tokens

max_tokens — De verouderde parameter. Werkt met de meeste modellen, maar is deprecated voor nieuwere OpenAI-modellen.
max_completion_tokens — De aanbevolen parameter voor GPT-4.1, GPT-5 series en o-series modellen. Vereist voor reasoning-modellen omdat deze zowel output tokens als reasoning tokens omvat.

CometAPI handelt de mapping automatisch af bij het routeren naar verschillende providers.

system vs developer role

system — De traditionele instructierol. Werkt met alle modellen.
developer — Geïntroduceerd met o1-modellen. Biedt sterkere instructie-opvolging voor nieuwere modellen. Valt terug op system-gedrag bij oudere modellen.

Gebruik developer voor nieuwe projecten die gericht zijn op GPT-4.1+ of o-series modellen.

FAQ

Hoe ga je om met rate limits?

Wanneer je 429 Too Many Requests tegenkomt, implementeer dan exponential backoff:

import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-5.4",
                messages=messages,
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

Hoe behoud je gesprekscontext?

Neem de volledige gespreksgeschiedenis op in de messages-array:

messages = [
    {"role": "developer", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a high-level programming language..."},
    {"role": "user", "content": "What are its main advantages?"},
]

Wat betekent `finish_reason`?

Value	Betekenis
`stop`	Natuurlijke voltooiing of een stop sequence bereikt.
`length`	Limiet van `max_tokens` of `max_completion_tokens` bereikt.
`tool_calls`	Het model heeft een of meer tool/function calls aangeroepen.
`content_filter`	Output is gefilterd vanwege het contentbeleid.

Hoe beheers je kosten?

Gebruik max_completion_tokens om de outputlengte te beperken.
Kies kostenefficiënte modellen (bijv. gpt-5.4-mini of gpt-5.4-nano voor eenvoudigere taken).
Houd prompts beknopt — vermijd overbodige context.
Monitor tokengebruik in het response-veld usage.

Autorisaties

Authorization

string

header

vereist

Bearer token authentication. Use your CometAPI key.

Body

application/json

model

string

standaard:gpt-5.4

vereist

Model ID to use for this request. See the Models page for current options.

Voorbeeld:

"gpt-4.1"

messages

object[]

vereist

A list of messages forming the conversation. Each message has a role (system, user, assistant, or developer) and content (text string or multimodal content array).

Show child attributes

stream

boolean

If true, partial response tokens are delivered incrementally via server-sent events (SSE). The stream ends with a data: [DONE] message.

temperature

number

standaard:1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) produce more random output; lower values (e.g., 0.2) make output more focused and deterministic. Recommended to adjust this or top_p, but not both.

Vereist bereik: 0 <= x <= 2

top_p

number

standaard:1

Nucleus sampling parameter. The model considers only the tokens whose cumulative probability reaches top_p. For example, 0.1 means only the top 10% probability tokens are considered. Recommended to adjust this or temperature, but not both.

Vereist bereik: 0 <= x <= 1

integer

standaard:1

Number of completion choices to generate for each input message. Defaults to 1.

stop

string

Up to 4 sequences where the API will stop generating further tokens. Can be a string or an array of strings.

max_tokens

integer

Maximum number of tokens to generate in the completion. The total of input + output tokens is capped by the model's context length.

presence_penalty

number

standaard:0

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared, encouraging the model to explore new topics.

Vereist bereik: -2 <= x <= 2

frequency_penalty

number

standaard:0

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

Vereist bereik: -2 <= x <= 2

logit_bias

object

A JSON object mapping token IDs to bias values from -100 to 100. The bias is added to the model's logits before sampling. Values between -1 and 1 subtly adjust likelihood; -100 or 100 effectively ban or force selection of a token.

user

string

A unique identifier for your end-user. Helps with abuse detection and monitoring.

max_completion_tokens

integer

An upper bound for the number of tokens to generate, including visible output tokens and reasoning tokens. Use this instead of max_tokens for GPT-4.1+, GPT-5 series, and o-series models.

response_format

object

Specifies the output format. Use {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {...}} for strict structured output.

Show child attributes

tools

object[]

A list of tools the model may call. Currently supports function type tools.

Show child attributes

tool_choice

standaard:auto

Controls how the model selects tools. auto (default): model decides. none: no tools. required: must call a tool.

logprobs

boolean

standaard:false

Whether to return log probabilities of the output tokens.

top_logprobs

integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

Vereist bereik: 0 <= x <= 20

reasoning_effort

enum<string>

Controls the reasoning effort for o-series and GPT-5.1+ models.

Beschikbare opties:

low,

medium,

high

stream_options

object

Options for streaming. Only valid when stream is true.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

Beschikbare opties:

auto,

default,

flex,

priority

Respons

200 - application/json

Successful chat completion response.

string

Unique completion identifier.

Voorbeeld:

"chatcmpl-abc123"

object

enum<string>

Beschikbare opties:

chat.completion

Voorbeeld:

"chat.completion"

created

integer

Unix timestamp of creation.

Voorbeeld:

1774412483

model

string

The model used (may include version suffix).

Voorbeeld:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

Voorbeeld:

"default"

system_fingerprint

string | null

Voorbeeld:

"fp_490a4ad033"

Overzicht

API-referentie

Integratiehandleidingen

Fouten

Prijzen & facturatie

Ondersteuning

Overzicht

Belangrijke opmerkingen

Berichtrollen

Multimodal Input

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Opmerkingen over providers heen

FAQ

Hoe ga je om met rate limits?

Hoe behoud je gesprekscontext?

Wat betekent `finish_reason`?

Hoe beheers je kosten?

Autorisaties

Body

Respons

Overzicht

API-referentie

Integratiehandleidingen

Fouten

Prijzen & facturatie

Ondersteuning

​Overzicht

​Belangrijke opmerkingen

​Berichtrollen

​Multimodal Input

​Streaming

​Structured Outputs

​Tool / Function Calling

​Response Fields

​Opmerkingen over providers heen

​FAQ

​Hoe ga je om met rate limits?

​Hoe behoud je gesprekscontext?

​Wat betekent finish_reason?

​Hoe beheers je kosten?

Autorisaties

Body

Respons

Overzicht

Belangrijke opmerkingen

Berichtrollen

Multimodal Input

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Opmerkingen over providers heen

FAQ

Hoe ga je om met rate limits?

Hoe behoud je gesprekscontext?

Wat betekent `finish_reason`?

Hoe beheers je kosten?