创建聊天补全 - 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-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

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

通过与 OpenAI 兼容的聊天补全 API 发送对话。使用 base_url="https://api.cometapi.com/v1" 和您的 CometAPI API 密钥配置 SDK。基础、图像、流式输出（Streaming）和结构化输出示例使用 gpt-6-astra。函数调用（Function Calling）示例使用 gpt-5.6-sol，对数概率示例使用 gpt-4.1。

请参阅 OpenAI 聊天补全参考了解参数定义。对于 GPT-6 Astra 工具调用，请使用响应，并遵循 OpenAI 模型指南.

消息角色

角色	说明
`system`	设置助手的行为和个性。置于对话开头。
`developer`	提供应用程序指令。GPT-6 Astra 示例使用此角色。
`user`	来自最终用户的消息。
`assistant`	之前的模型响应，用于维护对话历史记录。
`tool`	工具/函数调用的结果。必须包含与原始工具调用匹配的 `tool_call_id`。

使用 developer Astra 示例时，请在用户消息之前的 GPT-6 消息中放置应用程序指令。

发送多模态（Multimodal）输入

使用内容部分数组，将图像与文本一同发送：

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe the road and surrounding landscape in this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1200",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "reasoning_effort": "low",
  "max_completion_tokens": 4096
}

使用 image_url.detail 选择图像处理细节。此示例使用 high。

流式传输响应

要接收增量输出，请将 stream 设置为 true。响应通过以下方式传送 服务器发送事件（SSE)。文本以 chat.completion.chunk 对象的形式到达；这个简略示例包含最终的用量数据块：

data: {"choices":[{"delta":{"content":"","refusal":null,"role":"assistant"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[{"delta":{"content":"Hi"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

: Additional text deltas omitted

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk","usage":{"completion_tokens":12,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens":18,"prompt_tokens_details":{"audio_tokens":0,"cache_write_tokens":0,"cached_tokens":0},"total_tokens":30}}

data: [DONE]

要在流式输出（Streaming）响应中包含 Token 用量统计信息，请将 stream_options.include_usage 设置为 true。用量数据会在 [DONE] 之前的最终数据块中出现。数据块的 choices 数组可能为空；访问 choices[0] 之前请先检查它。

请求结构化输出

使用 response_format 请求结构化输出：

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France? Return the answer and your confidence as a number from 0 to 1."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "The answer to the question."
          },
          "confidence": {
            "type": "number",
            "description": "Confidence between zero and one."
          }
        },
        "required": [
          "answer",
          "confidence"
        ],
        "additionalProperties": false
      }
    }
  }
}

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with the key answer and the capital of France as its value."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_object"
  }
}

JSON Schema 模式规定所需结构。JSON Object 模式请求有效的 JSON，但不会强制执行你的 schema。使用结果前，请检查是否发生拒绝或响应是否受长度限制。

调用工具和函数

使用 gpt-5.6-sol 并提供函数定义：

{
  "model": "gpt-5.6-sol",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Boston, MA, in celsius? Use the weather tool."
    }
  ],
  "reasoning_effort": "none",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and state, for example Boston, MA."
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ],
              "description": "Temperature unit."
            }
          },
          "required": [
            "location",
            "unit"
          ],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}

函数调用会返回 finish_reason: "tool_calls" 和一个 message.tool_calls 数组。解析函数的 JSON 编码 arguments，执行函数，然后追加助手消息以及包含匹配的 tool 的 tool_call_id 结果消息。

选择请求参数

特定模型参数

将 reasoning_effort 和 max_completion_tokens 与 GPT-6 Astra 搭配使用。函数和 Logprobs 示例分别展示了 gpt-5.6-sol 和 gpt-4.1 的请求选项。如需了解 Claude 或 Gemini 特定的请求格式，请参阅 Anthropic 消息以及 Gemini 生成内容.

max_tokens 和 max_completion_tokens

使用 max_completion_tokens 限制 GPT-6 Astra 示例生成的 Token 数量。这包括推理和可见输出，因此请为两者预留空间。max_tokens 是旧版参数。

指令角色

在 developer Astra 示例中，使用 GPT-6 作为应用程序指令。将最终用户内容保留在 user 消息中，并在继续对话时保留先前的助手回复。

常见问题

如何处理速率限制？

遇到 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-6-astra",
                messages=messages,
                reasoning_effort="low",
            )
        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 限制输出长度。
比较模型定价，并选择满足工作负载要求的模型。
保持 Prompt 简洁，避免冗余上下文。
在 usage 响应字段中监控 Token 用量。

授权

Authorization

string

header

必填

Bearer token authentication. Use your CometAPI key.

请求体

application/json

model

string

默认值:gpt-6-astra

必填

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

示例:

"gpt-6-astra"

messages

object[]

必填

Conversation messages, including instructions, user input, assistant replies, and tool results.

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

Sampling temperature. Omit this field for GPT-6 Astra.

必填范围: 0 <= x <= 2

top_p

number

Nucleus sampling threshold. Omit this field for GPT-6 Astra. For sampling overrides, adjust either top_p or temperature.

必填范围: 0 <= x <= 1

integer

Number of completion choices to generate for each input message. Defaults to 1.

stop

Stop string or list of up to four strings, for models that support stop sequences.

max_tokens

integer

已弃用

Legacy output-token limit. Use max_completion_tokens for the GPT-6 Astra examples.

presence_penalty

number

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

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

Maximum generated tokens, including visible output and reasoning. Leave enough room for both, as in the image-input example.

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[]

Function definitions for a model that supports tool calling on Chat Completions. The function example uses GPT-5.6 Sol; use Responses for GPT-6 Astra tool calls.

Show child attributes

tool_choice

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

logprobs

boolean

Return token log probabilities. Use gpt-4.1 as shown in the Logprobs example.

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

string

Reasoning effort supported by the selected model. The GPT-6 Astra examples use low; the GPT-5.6 Sol function example uses none. See the model reference for other supported levels.

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

object

enum<string>

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

可用选项:

chat.completion

示例:

"chat.completion"

created

integer

Unix timestamp of creation.

示例:

1788763703

model

string

The model used (may include version suffix).

示例:

"gpt-6-astra"

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 returned.

system_fingerprint

string | null

Model configuration fingerprint, when returned.

最后修改于 2026年9月8日

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-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

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

​消息角色

​发送多模态（Multimodal）输入

​流式传输响应

​请求结构化输出

​调用工具和函数

​选择请求参数

​常见问题

​如何处理速率限制？

​如何维护对话上下文？

​finish_reason 是什么意思？

​如何控制成本？

授权

请求体

响应

消息角色

发送多模态（Multimodal）输入

流式传输响应

请求结构化输出

调用工具和函数

选择请求参数

常见问题

如何处理速率限制？

如何维护对话上下文？

`finish_reason` 是什么意思？

如何控制成本？