Maak een chat completion - CometAPI Documentation

POST

chat

completions

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

CometAPI routeert Chat Completions naar meerdere providers — waaronder OpenAI, Claude en Gemini — via één OpenAI-compatibele interface. Wissel tussen modellen door de parameter model te wijzigen; de meeste OpenAI-compatibele SDK’s werken door base_url in te stellen op https://api.cometapi.com/v1.

Aanvraagparameters en responsvelden kunnen aanzienlijk verschillen tussen modelproviders. Controleer de officiële documentatie van de provider achter het model dat je gebruikt wanneer je de volledige parameterlijst of provider-specifiek gedrag nodig hebt. Bijvoorbeeld, reasoning_effort is alleen van toepassing op reasoning-modellen (o-series, GPT-5.1+), en sommige modellen ondersteunen logprobs of n > 1 niet.

Gebruik voor OpenAI Pro-modellen, o-series reasoning-modellen en Codex-modellen in plaats daarvan het endpoint Responses. Deze modelfamilies hebben completere ondersteuning in de Responses API.

Berichtrollen

Role	Description
`system`	Stelt het gedrag en de persoonlijkheid van de assistent in. Wordt aan het begin van het gesprek geplaatst.
`developer`	Vervangt `system` voor nieuwere modellen (o1+). Geeft instructies die het model moet volgen, ongeacht invoer 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 gedrag bij het opvolgen van instructies.

Verstuur multimodale invoer

Veel modellen ondersteunen afbeeldingen en audio naast tekst. Gebruik de array-indeling voor content om multimodale berichten te verzenden:

{
  "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 diepte van de beeldanalyse:

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

Stream responsen

Stel stream in op true om incrementele output te ontvangen. De respons wordt geleverd als Server-Sent Events (SSE), waarbij elke gebeurtenis een chat.completion.chunk-object bevat:

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 tokengebruiksstatistieken op te nemen in streaming-responsen, stel je stream_options.include_usage in op true. De gebruiksgegevens verschijnen in de laatste chunk vóór [DONE].

Gestructureerde output aanvragen

Om het model te dwingen geldige JSON terug te geven die overeenkomt met een specifiek schema, gebruik je 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
      }
    }
  }
}

{
  "response_format": {"type": "json_object"}
}

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

Tools en functies aanroepen

Om het model in staat te stellen externe functies aan te roepen, geef je tooldefinities op:

{
  "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, zal de response finish_reason: "tool_calls" hebben en zal de array message.tool_calls de functienaam en argumenten bevatten. Vervolgens voer je de functie uit en stuur je het resultaat terug als een tool-bericht met de overeenkomende tool_call_id.

Opmerkingen voor meerdere providers

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 legacy-parameter. Werkt met de meeste modellen, maar is verouderd 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 verwerkt de mapping automatisch 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 zijn gericht op GPT-4.1+ of o-series-modellen.

FAQ

Hoe om te gaan met rate limits?

Wanneer je 429 Too Many Requests tegenkomt, implementeer dan exponentiële backoff:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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 stopsequentie 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 uitvoerlengte te begrenzen.
Kies kostenefficiënte modellen (bijv. gpt-5.4-mini of gpt-5.4-nano voor eenvoudigere taken).
Houd prompts beknopt — vermijd overbodige context.
Controleer Token-gebruik 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

Successful chat completion response.

string

Unique completion identifier.

Voorbeeld:

"chatcmpl-abc123"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

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-2026-03-05"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when the provider reports one.

Voorbeeld:

"default"

system_fingerprint

string | null

Provider backend configuration fingerprint, when the provider reports one.

Voorbeeld:

"fp_490a4ad033"

Tekst- en chat-API's

Maak een model response

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

​Berichtrollen

​Verstuur multimodale invoer

​Stream responsen

​Gestructureerde output aanvragen

​Tools en functies aanroepen

​Opmerkingen voor meerdere providers

​FAQ

​Hoe om te gaan met rate limits?

​Hoe behoud je gesprekscontext?

​Wat betekent finish_reason?

​Hoe beheers je kosten?

Autorisaties

Body

Respons

Berichtrollen

Verstuur multimodale invoer

Stream responsen

Gestructureerde output aanvragen

Tools en functies aanroepen

Opmerkingen voor meerdere providers

FAQ

Hoe om te gaan met rate limits?

Hoe behoud je gesprekscontext?

Wat betekent `finish_reason`?

Hoe beheers je kosten?