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 merutekan Chat Completions ke beberapa provider — termasuk OpenAI, Claude, dan Gemini — melalui satu antarmuka yang kompatibel dengan OpenAI. Beralih antar model dengan mengubah parameter model; sebagian besar SDK yang kompatibel dengan OpenAI dapat digunakan dengan menetapkan base_url ke https://api.cometapi.com/v1.

Model yang berbeda mendukung subset parameter yang berbeda dan mengembalikan field respons yang sedikit berbeda. Sebagai contoh, reasoning_effort hanya berlaku untuk model reasoning (o-series, GPT-5.1+), dan beberapa model tidak mendukung logprobs atau n > 1.

Untuk model OpenAI Pro, model reasoning o-series, dan model Codex, gunakan endpoint Responses sebagai gantinya. Keluarga model ini memiliki dukungan yang lebih lengkap pada API Responses.

Role pesan

Role	Deskripsi
`system`	Menetapkan perilaku dan kepribadian assistant. Ditempatkan di awal percakapan.
`developer`	Menggantikan `system` untuk model yang lebih baru (o1+). Memberikan instruksi yang harus diikuti model terlepas dari input pengguna.
`user`	Pesan dari pengguna akhir.
`assistant`	Respons model sebelumnya, digunakan untuk mempertahankan riwayat percakapan.
`tool`	Hasil dari pemanggilan tool/function. Harus menyertakan `tool_call_id` yang cocok dengan pemanggilan tool asli.

Untuk model yang lebih baru (GPT-4.1, GPT-5 series, o-series), utamakan developer daripada system untuk pesan instruksi. Keduanya berfungsi, tetapi developer memberikan perilaku mengikuti instruksi yang lebih kuat.

Kirim input multimodal

Banyak model mendukung gambar dan audio bersama teks. Untuk mengirim pesan multimodal, gunakan format array untuk content:

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

Parameter detail mengontrol kedalaman analisis gambar:

low — lebih cepat, menggunakan lebih sedikit token (biaya tetap)
high — analisis mendetail, lebih banyak token yang dikonsumsi
auto — model yang memutuskan (default)

Stream respons

Untuk menerima output secara bertahap, setel stream ke true. Respons dikirim sebagai Server-Sent Events (SSE), di mana setiap event berisi objek 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]

Untuk menyertakan statistik penggunaan token dalam respons streaming, setel stream_options.include_usage ke true. Data usage muncul pada chunk terakhir sebelum [DONE].

Minta output terstruktur

Untuk memaksa model mengembalikan JSON valid yang sesuai dengan schema tertentu, gunakan 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
      }
    }
  }
}

Mode JSON Schema (json_schema) menjamin output cocok persis dengan schema Anda. Mode JSON Object (json_object) hanya menjamin JSON yang valid — strukturnya tidak dipaksakan.

Panggil tools dan fungsi

Untuk mengaktifkan model memanggil fungsi eksternal, berikan definisi tool:

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

Saat model memutuskan untuk memanggil tool, respons akan memiliki finish_reason: "tool_calls" dan array message.tool_calls akan berisi nama fungsi serta argumennya. Anda kemudian menjalankan fungsi tersebut dan mengirimkan hasilnya kembali sebagai pesan tool dengan tool_call_id yang sesuai.

Catatan lintas provider

Dukungan parameter di berbagai 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	hanya 1	1–8
`stop`	Hingga 4	Hingga 4	Hingga 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (gunakan `thinking` untuk Gemini native)

max_tokens vs max_completion_tokens

max_tokens — Parameter lama. Berfungsi dengan sebagian besar model tetapi sudah deprecated untuk model OpenAI yang lebih baru.
max_completion_tokens — Parameter yang direkomendasikan untuk model GPT-4.1, seri GPT-5, dan o-series. Diperlukan untuk reasoning models karena mencakup output tokens dan reasoning tokens.

CometAPI secara otomatis menangani pemetaan saat melakukan routing ke provider yang berbeda.

system vs developer role

system — Role instruksi tradisional. Berfungsi dengan semua model.
developer — Diperkenalkan dengan model o1. Menyediakan kepatuhan instruksi yang lebih kuat untuk model yang lebih baru. Akan fallback ke perilaku system pada model yang lebih lama.

Gunakan developer untuk project baru yang menargetkan model GPT-4.1+ atau o-series.

FAQ

Bagaimana menangani rate limit?

Saat menemui 429 Too Many Requests, terapkan 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

Bagaimana mempertahankan konteks percakapan?

Sertakan riwayat percakapan lengkap dalam array 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?"},
]

Apa arti `finish_reason`?

Value	Arti
`stop`	Penyelesaian alami atau mencapai stop sequence.
`length`	Mencapai batas `max_tokens` atau `max_completion_tokens`.
`tool_calls`	Model memanggil satu atau lebih tool/function call.
`content_filter`	Output difilter karena kebijakan konten.

Bagaimana mengontrol biaya?

Gunakan max_completion_tokens untuk membatasi panjang output.
Pilih model yang hemat biaya (misalnya, gpt-5.4-mini atau gpt-5.4-nano untuk tugas yang lebih sederhana).
Buat prompt tetap ringkas — hindari konteks yang berulang.
Pantau penggunaan token di field respons usage.

Otorisasi

Authorization

string

header

wajib

Bearer token authentication. Use your CometAPI key.

Body

application/json

model

string

default:gpt-5.4

wajib

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

Contoh:

"gpt-4.1"

messages

object[]

wajib

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

default: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.

Rentang yang diperlukan: 0 <= x <= 2

top_p

number

default: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.

Rentang yang diperlukan: 0 <= x <= 1

integer

default: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

default: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.

Rentang yang diperlukan: -2 <= x <= 2

frequency_penalty

number

default:0

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

Rentang yang diperlukan: -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

default:auto

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

logprobs

boolean

default: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.

Rentang yang diperlukan: 0 <= x <= 20

reasoning_effort

enum<string>

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

Opsi yang tersedia:

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.

Opsi yang tersedia:

auto,

default,

flex,

priority

Respons

Successful chat completion response.

string

Unique completion identifier.

Contoh:

"chatcmpl-abc123"

object

enum<string>

Opsi yang tersedia:

chat.completion

Contoh:

"chat.completion"

created

integer

Unix timestamp of creation.

Contoh:

1774412483

model

string

The model used (may include version suffix).

Contoh:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

Contoh:

"default"

system_fingerprint

string | null

Contoh:

"fp_490a4ad033"

Responses

Selanjutnya

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

​Role pesan

​Kirim input multimodal

​Stream respons

​Minta output terstruktur

​Panggil tools dan fungsi

​Catatan lintas provider

​FAQ

​Bagaimana menangani rate limit?

​Bagaimana mempertahankan konteks percakapan?

​Apa arti finish_reason?

​Bagaimana mengontrol biaya?

Otorisasi

Body

Respons

Role pesan

Kirim input multimodal

Stream respons

Minta output terstruktur

Panggil tools dan fungsi

Catatan lintas provider

FAQ

Bagaimana menangani rate limit?

Bagaimana mempertahankan konteks percakapan?

Apa arti `finish_reason`?

Bagaimana mengontrol biaya?