Chat Completions - CometAPI Documentation

POST

chat

completions

from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<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"
}

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.

Verschillende modellen ondersteunen verschillende subsets van parameters en geven licht verschillende response-velden terug. 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 op de Responses API.

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 gebruikersinvoer.
`user`	Berichten van de eindgebruiker.
`assistant`	Eerdere modelresponses, gebruikt om de gespreksgeschiedenis te behouden.
`tool`	Resultaten van tool/function-calls. Moet `tool_call_id` bevatten die overeenkomt met de oorspronkelijke tool-call.

Geef voor nieuwere modellen (GPT-4.1, GPT-5 series, o-series) de voorkeur aan developer boven system voor instructieberichten. Beide werken, maar developer zorgt voor sterker gedrag bij het opvolgen van instructies.

Verstuur multimodale input

Veel modellen ondersteunen afbeeldingen en audio naast tekst. Om multimodale berichten te versturen, gebruik je het array-formaat voor content:

{
  "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 afbeeldingsanalyse:

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

Stream responses

Om incrementele output te ontvangen, stel je stream in op true. De response wordt geleverd als Server-Sent Events (SSE), waarbij elk event 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 statistieken over tokengebruik 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].

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

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 externe functies te laten aanroepen, 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, 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.

Opmerkingen over providers

Parameterondersteuning per provider

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 native Gemini)

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. Zorgt voor sterkere instructie-opvolging bij 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 om te gaan met rate limits?

Wanneer je 429 Too Many Requests tegenkomt, implementeer dan exponentiële 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 lengte van de output te begrenzen.
Kies kostenefficiënte modellen (bijv. gpt-5.4-mini of gpt-5.4-nano voor eenvoudigere taken).
Houd prompts beknopt — vermijd redundante context.
Controleer tokengebruik in het usage-responseveld.

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>

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"

Responses

from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<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"
}

Documentation Index

​Berichtrollen

​Verstuur multimodale input

​Stream responses

​Gestructureerde output aanvragen

​Tools en functies aanroepen

​Opmerkingen over 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 input

Stream responses

Gestructureerde output aanvragen

Tools en functies aanroepen

Opmerkingen over providers

FAQ

Hoe om te gaan met rate limits?

Hoe behoud je gesprekscontext?

Wat betekent `finish_reason`?

Hoe beheers je kosten?