Chat Completions

Огляд

Ендпоінт Chat Completions є найпоширенішим API для взаємодії з великими мовними моделями. Він приймає розмову, що складається з кількох повідомлень і повертає відповідь моделі. CometAPI маршрутизує цей ендпоінт до кількох провайдерів — зокрема OpenAI, Anthropic Claude (через шар сумісності), Google Gemini та інших — через єдиний уніфікований інтерфейс. Ви можете перемикатися між моделями, просто змінюючи параметр model.

Цей ендпоінт дотримується формату OpenAI Chat Completions. Більшість OpenAI-сумісних SDK та інструментів працюють із CometAPI, якщо змінити base_url на https://api.cometapi.com/v1.

Важливі примітки

Поведінка, специфічна для моделі — Різні моделі можуть підтримувати різні підмножини параметрів і повертати дещо відмінні поля відповіді. Наприклад, reasoning_effort застосовується лише до reasoning-моделей (o-series, GPT-5.1+), а деякі моделі можуть не підтримувати logprobs або n > 1.

Наскрізна передача відповіді — CometAPI передає відповіді моделей без змін (окрім нормалізації формату під час маршрутизації між провайдерами), гарантуючи, що ви отримуєте вивід, узгоджений з оригінальним API.

Моделі OpenAI Pro — Для моделей серії OpenAI Pro (наприклад, o1-pro) використовуйте ендпоінт responses натомість.

Ролі повідомлень

Role	Description
`system`	Визначає поведінку та стиль assistant. Розміщується на початку розмови.
`developer`	Замінює `system` для новіших моделей (o1+). Надає інструкції, яких модель має дотримуватися незалежно від введення користувача.
`user`	Повідомлення від кінцевого користувача.
`assistant`	Попередні відповіді моделі, що використовуються для збереження історії розмови.
`tool`	Результати викликів tool/function. Має містити `tool_call_id`, що відповідає оригінальному виклику tool.

Для новіших моделей (GPT-4.1, GPT-5 series, o-series) надавайте перевагу developer замість system для повідомлень з інструкціями. Обидва варіанти працюють, але developer забезпечує сильніше дотримання інструкцій.

Multimodal вхід

Багато моделей підтримують зображення й аудіо поряд із текстом. Використовуйте формат масиву для content, щоб надсилати multimodal-повідомлення:

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

Параметр detail керує глибиною аналізу зображення:

low — швидше, використовує менше tokens (фіксована вартість)
high — детальний аналіз, споживає більше tokens
auto — модель вирішує сама (за замовчуванням)

Streaming

Коли stream встановлено в true, відповідь передається як Server-Sent Events (SSE). Кожна подія містить об’єкт 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]

Щоб включити статистику використання token у Streaming-відповіді, встановіть stream_options.include_usage в true. Дані про використання з’являться в останньому chunk перед [DONE].

Structured Outputs

Примусьте model повертати валідний JSON, що відповідає конкретній схемі, використовуючи 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
      }
    }
  }
}

Режим JSON Schema (json_schema) гарантує, що вихідні дані точно відповідатимуть вашій схемі. Режим JSON Object (json_object) гарантує лише валідний JSON — структура не перевіряється.

Tool / Function Calling

Увімкніть для model можливість викликати зовнішні функції, надавши визначення інструментів:

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

Коли model вирішує викликати інструмент, відповідь матиме finish_reason: "tool_calls", а масив message.tool_calls міститиме назву функції та аргументи. Потім ви виконуєте функцію та надсилаєте результат назад як повідомлення tool з відповідним tool_call_id.

Response Fields

Field	Опис
`id`	Унікальний ідентифікатор completion (наприклад, `chatcmpl-abc123`).
`object`	Завжди `chat.completion`.
`model`	Model, яка згенерувала відповідь (може містити суфікс версії).
`choices`	Масив варіантів completion (зазвичай 1, якщо тільки `n` > 1).
`choices[].message`	Повідомлення відповіді assistant з `role`, `content` і, за потреби, `tool_calls`.
`choices[].finish_reason`	Чому model зупинилася: `stop`, `length`, `tool_calls` або `content_filter`.
`usage`	Розподіл споживання token: `prompt_tokens`, `completion_tokens`, `total_tokens` і детальні підрахунки підкатегорій.
`system_fingerprint`	Відбиток конфігурації бекенда для налагодження відтворюваності.

Примітки щодо крос-провайдерності

Підтримка параметрів у різних провайдерів

Parameter	OpenAI GPT	Claude (через compat)	Gemini (через compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	лише 1	1–8
`stop`	До 4	До 4	До 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (використовуйте `thinking` для нативного Gemini)

max_tokens vs max_completion_tokens

max_tokens — Застарілий параметр. Працює з більшістю моделей, але є deprecated для новіших моделей OpenAI.
max_completion_tokens — Рекомендований параметр для GPT-4.1, серії GPT-5 та моделей o-series. Обов’язковий для reasoning-моделей, оскільки охоплює як вихідні tokens, так і reasoning tokens.

CometAPI автоматично обробляє це зіставлення під час маршрутизації до різних провайдерів.

role system vs developer

system — Традиційна роль інструкцій. Працює з усіма моделями.
developer — Запроваджено з моделями o1. Забезпечує сильніше дотримання інструкцій у новіших моделях. Для старіших моделей повертається до поведінки system.

Використовуйте developer для нових проєктів, орієнтованих на GPT-4.1+ або моделі o-series.

FAQ

Як обробляти rate limits?

Коли ви отримуєте 429 Too Many Requests, реалізуйте 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

Як підтримувати контекст розмови?

Включайте повну історію розмови в масив 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?"},
]

Що означає `finish_reason`?

Value	Meaning
`stop`	Природне завершення або досягнуто stop-послідовність.
`length`	Досягнуто ліміту `max_tokens` або `max_completion_tokens`.
`tool_calls`	Модель викликала один або кілька tool/function calls.
`content_filter`	Вивід було відфільтровано через політику контенту.

Як контролювати витрати?

Використовуйте max_completion_tokens, щоб обмежити довжину виводу.
Обирайте економічні моделі (наприклад, gpt-5.4-mini або gpt-5.4-nano для простіших завдань).
Робіть prompts лаконічними — уникайте зайвого контексту.
Відстежуйте використання tokens у полі відповіді usage.

Авторизації

Authorization

string

header

обов'язково

Bearer token authentication. Use your CometAPI key.

Тіло

application/json

model

string

за замовчуванням:gpt-5.4

обов'язково

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

Приклад:

"gpt-4.1"

messages

object[]

обов'язково

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

за замовчуванням: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.

Необхідний діапазон: 0 <= x <= 2

top_p

number

за замовчуванням: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.

Необхідний діапазон: 0 <= x <= 1

integer

за замовчуванням: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

за замовчуванням: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.

Необхідний діапазон: -2 <= x <= 2

frequency_penalty

number

за замовчуванням:0

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

Необхідний діапазон: -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

за замовчуванням:auto

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

logprobs

boolean

за замовчуванням: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.

Необхідний діапазон: 0 <= x <= 20

reasoning_effort

enum<string>

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

Доступні опції:

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.

Доступні опції:

auto,

default,

flex,

priority

Відповідь

200 - application/json

Successful chat completion response.

string

Unique completion identifier.

Приклад:

"chatcmpl-abc123"

object

enum<string>

Доступні опції:

chat.completion

Приклад:

"chat.completion"

created

integer

Unix timestamp of creation.

Приклад:

1774412483

model

string

The model used (may include version suffix).

Приклад:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

Приклад:

"default"

system_fingerprint

string | null

Приклад:

"fp_490a4ad033"

Огляд

Довідник API

Посібники з інтеграції

Помилки

Ціни та оплата

Підтримка

Огляд

Важливі примітки

Ролі повідомлень

Multimodal вхід

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Примітки щодо крос-провайдерності

FAQ

Як обробляти rate limits?

Як підтримувати контекст розмови?

Що означає `finish_reason`?

Як контролювати витрати?

Авторизації

Тіло

Відповідь

Огляд

Довідник API

Посібники з інтеграції

Помилки

Ціни та оплата

Підтримка

​Огляд

​Важливі примітки

​Ролі повідомлень

​Multimodal вхід

​Streaming

​Structured Outputs

​Tool / Function Calling

​Response Fields

​Примітки щодо крос-провайдерності

​FAQ

​Як обробляти rate limits?

​Як підтримувати контекст розмови?

​Що означає finish_reason?

​Як контролювати витрати?

Авторизації

Тіло

Відповідь

Огляд

Важливі примітки

Ролі повідомлень

Multimodal вхід

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Примітки щодо крос-провайдерності

FAQ

Як обробляти rate limits?

Як підтримувати контекст розмови?

Що означає `finish_reason`?

Як контролювати витрати?