Chat Completions

Ikhtisar

Endpoint Chat Completions adalah API yang paling luas digunakan untuk berinteraksi dengan large language model. Endpoint ini menerima percakapan yang terdiri dari beberapa pesan dan mengembalikan respons model. CometAPI merutekan endpoint ini ke beberapa provider — termasuk OpenAI, Anthropic Claude (melalui lapisan kompatibilitas), Google Gemini, dan lainnya — melalui satu antarmuka terpadu. Anda dapat berpindah antar model hanya dengan mengubah parameter model.

Endpoint ini mengikuti format OpenAI Chat Completions. Sebagian besar SDK dan tool yang kompatibel dengan OpenAI dapat bekerja dengan CometAPI dengan mengubah base_url menjadi https://api.cometapi.com/v1.

Catatan Penting

Perilaku spesifik model — Model yang berbeda mungkin 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 mungkin tidak mendukung logprobs atau n > 1.

Pass-through respons — CometAPI meneruskan respons model tanpa modifikasi (kecuali normalisasi format saat merutekan antar provider), sehingga Anda menerima output yang konsisten dengan API aslinya.

Model OpenAI Pro — Untuk model seri OpenAI Pro (misalnya, o1-pro), gunakan endpoint responses sebagai gantinya.

Peran Pesan

Role	Description
`system`	Mengatur perilaku dan kepribadian asisten. 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, seri GPT-5, o-series), gunakan developer alih-alih system untuk pesan instruksi. Keduanya berfungsi, tetapi developer memberikan perilaku yang lebih kuat dalam mengikuti instruksi.

Input Multimodal

Banyak model mendukung gambar dan audio selain teks. Gunakan format array untuk content guna mengirim pesan multimodal:

{
  "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 dikonsumsi
auto — model yang memutuskan (default)

Streaming

Saat stream disetel ke true, respons dikirimkan sebagai Server-Sent Events (SSE). Setiap event berisi objek chat.completion.chunk dengan konten bertahap:

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 akan muncul pada chunk terakhir sebelum [DONE].

Structured Outputs

Paksa model untuk mengembalikan JSON valid yang cocok dengan schema tertentu menggunakan 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.

Tool / Function Calling

Aktifkan model untuk memanggil fungsi eksternal dengan menyediakan 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 mengeksekusi fungsi tersebut dan mengirimkan hasilnya kembali sebagai pesan tool dengan tool_call_id yang sesuai.

Response Fields

Field	Deskripsi
`id`	Pengidentifikasi completion yang unik (mis. `chatcmpl-abc123`).
`object`	Selalu `chat.completion`.
`model`	Model yang menghasilkan respons (dapat mencakup sufiks versi).
`choices`	Array pilihan completion (biasanya 1 kecuali `n` > 1).
`choices[].message`	Pesan respons assistant dengan `role`, `content`, dan opsional `tool_calls`.
`choices[].finish_reason`	Alasan model berhenti: `stop`, `length`, `tool_calls`, atau `content_filter`.
`usage`	Rincian konsumsi Token: `prompt_tokens`, `completion_tokens`, `total_tokens`, dan sub-jumlah terperinci.
`system_fingerprint`	Fingerprint konfigurasi backend untuk debugging reproduktibilitas.

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. Wajib untuk model reasoning karena mencakup output tokens dan reasoning tokens.

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

role system vs developer

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

Gunakan developer untuk proyek 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 context percakapan?

Sertakan seluruh riwayat percakapan 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`	Selesai secara 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).
Jaga agar prompt tetap ringkas — hindari context yang redundan.
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

200 - application/json

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"

Ikhtisar

Referensi API

Panduan Integrasi

Kesalahan

Harga & Penagihan

Dukungan

Ikhtisar

Catatan Penting

Peran Pesan

Input Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Catatan Lintas-Provider

FAQ

Bagaimana menangani rate limit?

Bagaimana mempertahankan context percakapan?

Apa arti `finish_reason`?

Bagaimana mengontrol biaya?

Otorisasi

Body

Respons

Ikhtisar

Referensi API

Panduan Integrasi

Kesalahan

Harga & Penagihan

Dukungan

​Ikhtisar

​Catatan Penting

​Peran Pesan

​Input Multimodal

​Streaming

​Structured Outputs

​Tool / Function Calling

​Response Fields

​Catatan Lintas-Provider

​FAQ

​Bagaimana menangani rate limit?

​Bagaimana mempertahankan context percakapan?

​Apa arti finish_reason?

​Bagaimana mengontrol biaya?

Otorisasi

Body

Respons

Ikhtisar

Catatan Penting

Peran Pesan

Input Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Catatan Lintas-Provider

FAQ

Bagaimana menangani rate limit?

Bagaimana mempertahankan context percakapan?

Apa arti `finish_reason`?

Bagaimana mengontrol biaya?