Chat Completions

Gunakan CometAPI POST /v1/chat/completions untuk mengirim percakapan multi-pesan dan mendapatkan balasan LLM dengan kontrol streaming, temperature, dan max_tokens.

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

​

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:

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

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?

1. Gunakan max_completion_tokens untuk membatasi panjang output.
2. Pilih model yang hemat biaya (misalnya, gpt-5.4-mini atau gpt-5.4-nano untuk tugas yang lebih sederhana).
3. Jaga agar prompt tetap ringkas — hindari context yang redundan.
4. 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

n · 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 · string object · 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.

id · 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"