Chat Completions

Verwenden Sie CometAPI POST /v1/chat/completions, um Unterhaltungen mit mehreren Nachrichten zu senden und LLM-Antworten mit Streaming-, temperature- und max_tokens-Steuerung zu erhalten.

POST /v1/chat/completions

Python

Default

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)

200

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

​

Überblick

Der Chat Completions-Endpunkt ist die am weitesten verbreitete API für die Interaktion mit großen Sprachmodellen. Er akzeptiert eine Unterhaltung, die aus mehreren Nachrichten besteht, und gibt die Antwort des Modells zurück.

CometAPI leitet diesen Endpunkt über eine einzige einheitliche Schnittstelle an mehrere Anbieter weiter — darunter OpenAI, Anthropic Claude (über eine Kompatibilitätsschicht), Google Gemini und andere. Sie können zwischen Modellen wechseln, indem Sie einfach den Parameter model ändern.

Dieser Endpunkt folgt dem OpenAI Chat Completions-Format. Die meisten OpenAI-kompatiblen SDKs und Tools funktionieren mit CometAPI, wenn Sie base_url auf https://api.cometapi.com/v1 ändern.

​

Wichtige Hinweise

Modellspezifisches Verhalten — Verschiedene Modelle unterstützen möglicherweise unterschiedliche Teilmengen von Parametern und geben leicht unterschiedliche Antwortfelder zurück. Zum Beispiel gilt reasoning_effort nur für Reasoning-Modelle (o-series, GPT-5.1+), und einige Modelle unterstützen möglicherweise logprobs oder n > 1 nicht.

Unveränderte Weitergabe der Antwort — CometAPI gibt Modellantworten ohne Änderungen weiter (außer bei der Formatnormalisierung beim Routing zwischen Anbietern), sodass Sie Ausgaben erhalten, die mit der ursprünglichen API konsistent sind.

OpenAI Pro-Modelle — Für Modelle der OpenAI Pro-Serie (z. B. o1-pro) verwenden Sie stattdessen den Endpunkt responses.

---

​

Nachrichtenrollen

Role	Description
system	Legt das Verhalten und die Persönlichkeit des Assistenten fest. Wird am Anfang der Unterhaltung platziert.
developer	Ersetzt system bei neueren Modellen (o1+). Stellt Anweisungen bereit, denen das Modell unabhängig von der Benutzereingabe folgen soll.
user	Nachrichten vom Endbenutzer.
assistant	Vorherige Modellantworten, die verwendet werden, um den Unterhaltungsverlauf beizubehalten.
tool	Ergebnisse von Tool-/Function Calling-Aufrufen. Muss tool_call_id enthalten, das dem ursprünglichen Tool-Aufruf entspricht.

Für neuere Modelle (GPT-4.1, GPT-5-Serie, o-series) sollten Sie für Anweisungsnachrichten developer statt system bevorzugen. Beide funktionieren, aber developer sorgt für ein stärkeres Befolgen von Anweisungen.

---

​

Multimodal Input

Viele Modelle unterstützen Bilder und Audio zusätzlich zu Text. Verwenden Sie das Array-Format für content, um multimodale Nachrichten zu senden:

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

Der Parameter detail steuert die Tiefe der Bildanalyse:

• low — schneller, verwendet weniger Tokens (feste Kosten)
• high — detaillierte Analyse, mehr Tokens werden verbraucht
• auto — das Modell entscheidet (Standard)

---

​

Streaming

Wenn stream auf true gesetzt ist, wird die Antwort als Server-Sent Events (SSE) übermittelt. Jedes Event enthält ein chat.completion.chunk-Objekt mit inkrementellem Inhalt:

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]

Um Statistiken zur Token-Nutzung in Streaming-Antworten einzuschließen, setzen Sie stream_options.include_usage auf true. Die Nutzungsdaten erscheinen im letzten Chunk vor [DONE].

---

​

Structured Outputs

Erzwingen Sie, dass das model gültiges JSON zurückgibt, das mithilfe von response_format einem bestimmten Schema entspricht:

JSON Schema Mode

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

Der JSON Schema-Modus (json_schema) garantiert, dass die Ausgabe exakt Ihrem Schema entspricht. Der JSON Object-Modus (json_object) garantiert nur gültiges JSON — die Struktur wird nicht erzwungen.

---

​

Tool / Function Calling

Aktivieren Sie, dass das model externe Funktionen aufrufen kann, indem Sie Tool-Definitionen bereitstellen:

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

Wenn das model entscheidet, ein Tool aufzurufen, enthält die Antwort finish_reason: "tool_calls" und das Array message.tool_calls enthält den Funktionsnamen und die Argumente. Anschließend führen Sie die Funktion aus und senden das Ergebnis als tool-Nachricht mit der passenden tool_call_id zurück.

---

​

Response Fields

Feld	Beschreibung
id	Eindeutiger Bezeichner der Completion (z. B. chatcmpl-abc123).
object	Immer chat.completion.
model	Das model, das die Antwort erzeugt hat (kann ein Versionssuffix enthalten).
choices	Array mit Completion-Auswahlen (typischerweise 1, außer wenn n > 1).
choices[].message	Die Antwortnachricht des assistant mit role, content und optional tool_calls.
choices[].finish_reason	Warum das model angehalten hat: stop, length, tool_calls oder content_filter.
usage	Aufschlüsselung des Token-Verbrauchs: prompt_tokens, completion_tokens, total_tokens und detaillierte Unterzählungen.
system_fingerprint	Fingerprint der Backend-Konfiguration zur Reproduzierbarkeit beim Debugging.

---

​

Hinweise zu providerübergreifenden Unterschieden

Parameterunterstützung über verschiedene Provider hinweg

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	nur 1	1–8
stop	Bis zu 4	Bis zu 4	Bis zu 5
tools	✅	✅	✅
response_format	✅	✅ (json_schema)	✅
logprobs	✅	❌	❌
reasoning_effort	o-series, GPT-5.1+	❌	❌ (verwenden Sie thinking für Gemini native)

max_tokens vs max_completion_tokens

• max_tokens — Der ältere Parameter. Funktioniert mit den meisten Modellen, ist aber für neuere OpenAI-Modelle veraltet.
• max_completion_tokens — Der empfohlene Parameter für GPT-4.1-, GPT-5-series- und o-series-Modelle. Erforderlich für Reasoning-Modelle, da er sowohl output tokens als auch reasoning tokens umfasst.

CometAPI übernimmt das Mapping automatisch, wenn an unterschiedliche Provider weitergeleitet wird.

system vs developer role

• system — Die traditionelle Instruktionsrolle. Funktioniert mit allen Modellen.
• developer — Eingeführt mit o1-Modellen. Bietet für neuere Modelle eine stärkere Befolgung von Anweisungen. Fällt bei älteren Modellen auf das Verhalten von system zurück.

Verwenden Sie developer für neue Projekte, die auf GPT-4.1+ oder o-series-Modelle abzielen.

---

​

FAQ

​

Wie geht man mit Rate Limits um?

Wenn 429 Too Many Requests auftritt, implementieren Sie exponentielles 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

​

Wie behält man den Konversationskontext bei?

Nehmen Sie den vollständigen Konversationsverlauf in das messages-Array auf:

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?"},
]

​

Was bedeutet finish_reason?

Value	Bedeutung
stop	Natürlicher Abschluss oder eine stop sequence wurde erreicht.
length	Das max_tokens- oder max_completion_tokens-Limit wurde erreicht.
tool_calls	Das Modell hat einen oder mehrere tool/function calls aufgerufen.
content_filter	Die Ausgabe wurde aufgrund von Inhaltsrichtlinien gefiltert.

​

Wie kontrolliert man die Kosten?

1. Verwenden Sie max_completion_tokens, um die Ausgabelänge zu begrenzen.
2. Wählen Sie kosteneffiziente Modelle (z. B. gpt-5.4-mini oder gpt-5.4-nano für einfachere Aufgaben).
3. Halten Sie Prompts knapp — vermeiden Sie redundanten Kontext.
4. Überwachen Sie die Token-Nutzung im Antwortfeld usage.

Autorisierungen

Authorization · string · header · erforderlich

Bearer token authentication. Use your CometAPI key.

Body

application/json

model · string · Standard: gpt-5.4 · erforderlich

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

Beispiel:

"gpt-4.1"

messages · object[] · erforderlich

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 · Standard: 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.

Erforderlicher Bereich: 0 <= x <= 2

top_p · number · Standard: 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.

Erforderlicher Bereich: 0 <= x <= 1

n · integer · Standard: 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 · Standard: 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.

Erforderlicher Bereich: -2 <= x <= 2

frequency_penalty · number · Standard: 0

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

Erforderlicher Bereich: -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 · string object · Standard: auto

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

logprobs · boolean · Standard: 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.

Erforderlicher Bereich: 0 <= x <= 20

reasoning_effort · enum<string>

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

Verfügbare Optionen: 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.

Verfügbare Optionen: auto, default, flex, priority

Antwort

200 - application/json

Successful chat completion response.

id · string

Unique completion identifier.

Beispiel:

"chatcmpl-abc123"

object · enum<string>

Verfügbare Optionen: chat.completion

Beispiel:

"chat.completion"

created · integer

Unix timestamp of creation.

Beispiel:

1774412483

model · string

The model used (may include version suffix).

Beispiel:

"gpt-5.4-2025-07-16"

choices · object[]

Array of completion choices.

Show child attributes

usage · object

Show child attributes

service_tier · string

Beispiel:

"default"

system_fingerprint · string | null

Beispiel:

"fp_490a4ad033"