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 achemine les Chat Completions vers plusieurs fournisseurs — notamment OpenAI, Claude et Gemini — via une interface unique compatible OpenAI. Passez d’un modèle à l’autre en modifiant le paramètre model ; la plupart des SDK compatibles OpenAI fonctionnent en définissant base_url sur https://api.cometapi.com/v1.

Différents modèles prennent en charge différents sous-ensembles de paramètres et renvoient des champs de réponse légèrement différents. Par exemple, reasoning_effort s’applique uniquement aux modèles de raisonnement (o-series, GPT-5.1+), et certains modèles ne prennent pas en charge logprobs ni n > 1.

Pour les modèles OpenAI Pro, les modèles de raisonnement o-series et les modèles Codex, utilisez plutôt le point de terminaison Responses. Ces familles de modèles bénéficient d’une prise en charge plus complète dans l’API Responses.

Rôles des messages

Role	Description
`system`	Définit le comportement et la personnalité de l’assistant. Placé au début de la conversation.
`developer`	Remplace `system` pour les modèles plus récents (o1+). Fournit des instructions que le modèle doit suivre quelle que soit l’entrée de l’utilisateur.
`user`	Messages de l’utilisateur final.
`assistant`	Réponses précédentes du modèle, utilisées pour conserver l’historique de la conversation.
`tool`	Résultats des appels d’outil/de fonction. Doit inclure `tool_call_id` correspondant à l’appel d’outil d’origine.

Pour les modèles plus récents (GPT-4.1, série GPT-5, o-series), préférez developer à system pour les messages d’instruction. Les deux fonctionnent, mais developer fournit un comportement de suivi des instructions plus fort.

Envoyer une entrée multimodale

De nombreux modèles prennent en charge les images et l’audio en plus du texte. Pour envoyer des messages multimodaux, utilisez le format tableau pour content :

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

Le paramètre detail contrôle la profondeur d’analyse de l’image :

low — plus rapide, utilise moins de tokens (coût fixe)
high — analyse détaillée, plus de tokens consommés
auto — le modèle décide (par défaut)

Diffuser les réponses en streaming

Pour recevoir une sortie incrémentielle, définissez stream sur true. La réponse est fournie sous forme de Server-Sent Events (SSE), où chaque événement contient un objet chat.completion.chunk :

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]

Pour inclure les statistiques d’utilisation des tokens dans les réponses en streaming, définissez stream_options.include_usage sur true. Les données d’utilisation apparaissent dans le dernier chunk avant [DONE].

Demander une sortie structurée

Pour forcer le modèle à renvoyer un JSON valide correspondant à un schéma spécifique, utilisez 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
      }
    }
  }
}

Le mode JSON Schema (json_schema) garantit que la sortie correspond exactement à votre schéma. Le mode JSON Object (json_object) garantit uniquement un JSON valide — la structure n’est pas imposée.

Appeler des outils et des fonctions

Pour permettre au modèle d’appeler des fonctions externes, fournissez des définitions d’outils :

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

Lorsque le modèle décide d’appeler un outil, la réponse aura finish_reason: "tool_calls" et le tableau message.tool_calls contiendra le nom de la fonction et les arguments. Vous exécutez ensuite la fonction et renvoyez le résultat sous forme de message tool avec le tool_call_id correspondant.

Remarques inter-fournisseurs

Prise en charge des paramètres selon les fournisseurs

Paramètre	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	1 uniquement	1–8
`stop`	Jusqu’à 4	Jusqu’à 4	Jusqu’à 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	série o, GPT-5.1+	❌	❌ (utilisez `thinking` pour Gemini natif)

max_tokens vs max_completion_tokens

max_tokens — Le paramètre historique. Fonctionne avec la plupart des modèles mais est obsolète pour les modèles OpenAI plus récents.
max_completion_tokens — Le paramètre recommandé pour les modèles GPT-4.1, série GPT-5 et série o. Requis pour les modèles de raisonnement, car il inclut à la fois les tokens de sortie et les tokens de raisonnement.

CometAPI gère automatiquement le mapping lors du routage vers différents fournisseurs.

rôle system vs developer

system — Le rôle d’instruction traditionnel. Fonctionne avec tous les modèles.
developer — Introduit avec les modèles o1. Fournit un suivi des instructions plus strict pour les modèles plus récents. Revient au comportement de system sur les anciens modèles.

Utilisez developer pour les nouveaux projets ciblant GPT-4.1+ ou les modèles de la série o.

FAQ

Comment gérer les limites de débit ?

Lorsque vous rencontrez 429 Too Many Requests, implémentez un backoff exponentiel :

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

Comment maintenir le contexte de conversation ?

Incluez l’historique complet de la conversation dans le tableau messages :

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

Que signifie `finish_reason` ?

Value	Meaning
`stop`	Fin naturelle ou atteinte d’une séquence d’arrêt.
`length`	Limite `max_tokens` ou `max_completion_tokens` atteinte.
`tool_calls`	Le modèle a invoqué un ou plusieurs appels d’outil/fonction.
`content_filter`	La sortie a été filtrée en raison de la politique de contenu.

Comment contrôler les coûts ?

Utilisez max_completion_tokens pour plafonner la longueur de sortie.
Choisissez des modèles économiques (par ex. gpt-5.4-mini ou gpt-5.4-nano pour les tâches plus simples).
Gardez les prompts concis — évitez le contexte redondant.
Surveillez l’utilisation des tokens dans le champ de réponse usage.

Autorisations

Authorization

string

header

requis

Bearer token authentication. Use your CometAPI key.

Corps

application/json

model

string

défaut:gpt-5.4

requis

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

Exemple:

"gpt-4.1"

messages

object[]

requis

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

défaut: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.

Plage requise: 0 <= x <= 2

top_p

number

défaut: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.

Plage requise: 0 <= x <= 1

integer

défaut: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

défaut: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.

Plage requise: -2 <= x <= 2

frequency_penalty

number

défaut:0

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

Plage requise: -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

défaut:auto

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

logprobs

boolean

défaut: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.

Plage requise: 0 <= x <= 20

reasoning_effort

enum<string>

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

Options disponibles:

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.

Options disponibles:

auto,

default,

flex,

priority

Réponse

Successful chat completion response.

string

Unique completion identifier.

Exemple:

"chatcmpl-abc123"

object

enum<string>

Options disponibles:

chat.completion

Exemple:

"chat.completion"

created

integer

Unix timestamp of creation.

Exemple:

1774412483

model

string

The model used (may include version suffix).

Exemple:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

Exemple:

"default"

system_fingerprint

string | null

Exemple:

"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

​Rôles des messages

​Envoyer une entrée multimodale

​Diffuser les réponses en streaming

​Demander une sortie structurée

​Appeler des outils et des fonctions

​Remarques inter-fournisseurs

​FAQ

​Comment gérer les limites de débit ?

​Comment maintenir le contexte de conversation ?

​Que signifie finish_reason ?

​Comment contrôler les coûts ?

Autorisations

Corps

Réponse

Rôles des messages

Envoyer une entrée multimodale

Diffuser les réponses en streaming

Demander une sortie structurée

Appeler des outils et des fonctions

Remarques inter-fournisseurs

FAQ

Comment gérer les limites de débit ?

Comment maintenir le contexte de conversation ?

Que signifie `finish_reason` ?

Comment contrôler les coûts ?