建立聊天補全

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.6-sol",
    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"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

CometAPI 透過單一 OpenAI 相容介面，將聊天補全路由至多個供應商，包括 OpenAI、Claude 和 Gemini。變更 model 參數即可切換模型；大多數 OpenAI 相容 SDK 只要將 base_url 設為 https://api.cometapi.com/v1 即可運作。

不同模型供應商之間的請求參數和回應欄位可能有很大差異。當您需要完整參數清單或供應商特定行為時，請查閱您所用模型背後供應商的官方文件。例如，reasoning_effort 僅適用於推理模型（o-series、GPT-5.1+），且部分模型不支援 logprobs 或 n > 1。

對於 OpenAI Pro 模型、o-series 推理模型和 Codex 模型，請改用回應端點。這些模型系列在 Responses API 上獲得更完整的支援。

訊息角色

角色	說明
`system`	設定助理的行為和個性。置於對話開頭。
`developer`	取代較新模型（o1+）中的 `system`。提供模型無論使用者輸入為何都應遵循的指示。
`user`	來自終端使用者的訊息。
`assistant`	先前的模型回應，用於維持對話歷程。
`tool`	工具／函式呼叫的結果。必須包含與原始工具呼叫相符的 `tool_call_id`。

對於較新模型（GPT-4.1、GPT-5 系列、o-series），指示訊息應優先使用 developer 而非 system。兩者皆可運作，但 developer 提供更強的指示遵循行為。

傳送多模態輸入

許多模型除了文字外也支援圖片和音訊。若要傳送多模態訊息，請對 content 使用陣列格式：

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

detail 參數可控制圖片分析深度：

low — 速度更快，使用較少 Token（固定成本)
high — 詳細分析，消耗較多 Token
auto — 由模型決定（預設)

串流回應

若要接收增量輸出，請將 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 使用統計資料，請將 stream_options.include_usage 設為 true。使用量資料會顯示在 [DONE] 之前的最終區塊中。

請求結構化輸出

若要強制模型傳回符合特定結構描述的有效 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
      }
    }
  }
}

{
  "response_format": {"type": "json_object"}
}

JSON Schema 模式（json_schema）可保證輸出完全符合您的結構描述。JSON Object 模式（json_object）僅保證有效 JSON，不會強制結構。

呼叫工具和函式

若要讓模型能夠呼叫外部函式，請提供工具定義：

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

當模型決定呼叫工具時，回應將包含 finish_reason: "tool_calls"，而 message.tool_calls 陣列將包含函式名稱和引數。接著執行該函式，並將結果以帶有相符 tool_call_id 的 tool 訊息傳回。

跨供應商注意事項

各供應商的參數支援情況

參數	OpenAI GPT	Claude（透過相容)	Gemini（透過相容)
`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+	❌	❌ (原生 Gemini 請使用 `thinking`)

max_tokens 與 max_completion_tokens

max_tokens — 舊版參數。可搭配大多數模型使用，但已不建議用於較新的 OpenAI 模型。
max_completion_tokens — GPT-4.1、GPT-5 系列和 o-series 模型建議使用的參數。推理模型必須使用，因為它同時包含輸出 Token 和推理 Token。

CometAPI 在路由至不同供應商時會自動處理對應。

system 與 developer 角色

system — 傳統的指示角色。適用於所有模型。
developer — 隨 o1 模型推出。為較新模型提供更強的指示遵循能力。在較舊模型上會回退為 system 行為。

針對 GPT-4.1+ 或 o-series 模型的新專案，請使用 developer。

常見問題

如何處理速率限制？

遇到 429 Too Many Requests 時，請實作指數退避：

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.6-sol",
                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` 代表什麼？

值	含義
`stop`	自然完成或觸及停止序列。
`length`	已達到 `max_tokens` 或 `max_completion_tokens` 限制。
`tool_calls`	模型已呼叫一個或多個工具／函式。
`content_filter`	因內容政策而篩選輸出。

如何控制成本？

使用 max_completion_tokens 限制輸出長度。
使用 gpt-5.6-terra 平衡智慧與成本，或使用 gpt-5.6-luna 處理高效率的大量工作負載。
保持 Prompt 簡潔，避免重複的上下文。
在 usage 回應欄位中監控 Token 使用量。

授權

Authorization

string

header

必填

Bearer token authentication. Use your CometAPI key.

主體

application/json

model

string

預設值:gpt-5.6-sol

必填

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

回應

Successful chat completion response.

string

Unique completion identifier.

範例:

"chatcmpl-abc123"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

可用選項:

chat.completion

範例:

"chat.completion"

created

integer

Unix timestamp of creation.

範例:

1774412483

model

string

The model used (may include version suffix).

範例:

"gpt-5.4-2026-03-05"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when the provider reports one.

範例:

"default"

system_fingerprint

string | null

Provider backend configuration fingerprint, when the provider reports one.

範例:

"fp_490a4ad033"

文字與聊天 API

建立模型回應

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.6-sol",
    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"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

內容審核

API 金鑰

訊息角色

傳送多模態輸入

串流回應

請求結構化輸出

呼叫工具和函式

跨供應商注意事項

常見問題

如何處理速率限制？

如何維持對話上下文？

`finish_reason` 代表什麼？

如何控制成本？

授權

主體

回應

​訊息角色

​傳送多模態輸入

​串流回應

​請求結構化輸出

​呼叫工具和函式

​跨供應商注意事項

​常見問題

​如何處理速率限制？

​如何維持對話上下文？

​finish_reason 代表什麼？

​如何控制成本？

授權

主體

回應

訊息角色

傳送多模態輸入

串流回應

請求結構化輸出

呼叫工具和函式

跨供應商注意事項

常見問題

如何處理速率限制？

如何維持對話上下文？

`finish_reason` 代表什麼？

如何控制成本？