Chat Completions - CometAPI Documentation

POST

chat

completions

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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 penyedia — termasuk OpenAI, Claude, dan Gemini — melalui satu antarmuka yang kompatibel dengan OpenAI. Beralih antarmodel dengan mengubah parameter model; sebagian besar SDK yang kompatibel dengan OpenAI bekerja dengan menetapkan base_url ke https://api.cometapi.com/v1.

Parameter request dan field respons dapat sangat bervariasi di antara penyedia model. Periksa dokumentasi resmi untuk penyedia di balik model yang Anda gunakan setiap kali Anda memerlukan daftar parameter lengkap atau perilaku khusus penyedia. Misalnya, reasoning_effort hanya berlaku untuk reasoning models (o-series, GPT-5.1+), dan beberapa model tidak mendukung logprobs atau n > 1.

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

Peran message

Role	Description
`system`	Menetapkan perilaku dan kepribadian assistant. Ditempatkan di awal percakapan.
`developer`	Menggantikan `system` untuk model yang lebih baru (o1+). Menyediakan instruksi yang harus diikuti model apa pun input user.
`user`	Message dari user akhir.
`assistant`	Respons model sebelumnya, digunakan untuk mempertahankan riwayat percakapan.
`tool`	Hasil dari panggilan tool/function. Harus menyertakan `tool_call_id` yang cocok dengan panggilan tool asli.

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

Kirim input multimodal

Banyak model mendukung gambar dan audio bersama teks. Untuk mengirim message 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 tokens (biaya tetap)
high — analisis mendetail, lebih banyak tokens dikonsumsi
auto — model yang menentukan (default)

Stream responses

Untuk menerima output bertahap, set 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 tokens dalam streaming responses, set stream_options.include_usage ke true. Data usage muncul pada chunk terakhir sebelum [DONE].

Meminta output terstruktur

Untuk memaksa model mengembalikan JSON valid yang cocok dengan skema 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 skema Anda. Mode JSON Object (json_object) hanya menjamin JSON yang valid — strukturnya tidak dipaksakan.

Memanggil tools dan functions

Untuk mengaktifkan model agar dapat memanggil function 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 function dan argumennya. Anda lalu menjalankan function 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 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.

system vs developer role

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

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

FAQ

Bagaimana menangani rate limits?

Saat menemui 429 Too Many Requests, terapkan exponential backoff:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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 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	Meaning
`stop`	Penyelesaian alami atau mencapai stop sequence.
`length`	Mencapai batas `max_tokens` atau `max_completion_tokens`.
`tool_calls`	Model memanggil satu atau beberapa 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 atau gpt-5.4-nano untuk tugas yang lebih sederhana).
Buat prompt sesingkat mungkin — 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"

Model teks mana yang bisa saya gunakan dengan CometAPI?

Sebelumnya

Responses

Selanjutnya

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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"
}

​Peran message

​Kirim input multimodal

​Stream responses

​Meminta output terstruktur

​Memanggil tools dan functions

​Catatan lintas-provider

​FAQ

​Bagaimana menangani rate limits?

​Bagaimana mempertahankan konteks percakapan?

​Apa arti finish_reason?

​Bagaimana mengontrol biaya?

Otorisasi

Body

Respons

Peran message

Kirim input multimodal

Stream responses

Meminta output terstruktur

Memanggil tools dan functions

Catatan lintas-provider

FAQ

Bagaimana menangani rate limits?

Bagaimana mempertahankan konteks percakapan?

Apa arti `finish_reason`?

Bagaimana mengontrol biaya?