Chat Completions API

使用 Chat Completions API 进行对话生成，兼容 OpenAI 格式。

Chat Completions API 是最核心的端点，支持多轮对话、流式输出、推理模式、知识库搜索和联网搜索等功能。完全兼容 OpenAI Chat Completions 格式，可直接替换 base_url 使用。

核心请求参数

参数	类型	必填	说明
model	string	Required	模型 ID，如 "anthropic-claude-sonnet-4-6"、"gemini-2.5-flash"
messages	array	Required	对话消息数组，每条含 role（system/user/assistant）和 content
temperature	float	Optional	采样温度，0.0 - 2.0。值越高输出越随机，默认由模型决定
top_p	float	Optional	核采样参数，0.0 - 1.0，默认 1.0
max_tokens	integer	Optional	最大生成 token 数，默认由模型决定
stream	boolean	Optional	是否启用流式响应，默认 false

请求示例

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aideskapp.com/v1",
    api_key="sk-aidesk-YOUR_KEY"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)

响应字段说明

字段	类型	说明
id	string	补全的唯一标识符
object	string	固定为 `"chat.completion"`
created	integer	创建时间的 Unix 时间戳
model	string	生成补全时使用的模型 ID
choices	array	补全选项列表，每项含 `message` 和 `finish_reason`
choices[].message	object	包含 `role`、`content`，推理模型还有 `reasoning_content`
usage	object	Token 用量：prompt_tokens、completion_tokens、total_tokens、reasoning_tokens、cached_tokens
provider	string	实际处理请求的提供商标识
aidesk_kb_context	array	知识库检索上下文（启用 kb_search 时返回）
aidesk_web_context	array	联网搜索上下文（启用 web_search 时返回）

响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1746528000,
  "model": "anthropic-claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是 AI 助手，有什么可以帮你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43,
    "reasoning_tokens": 0,
    "cached_tokens": 0
  },
  "provider": "openai"
}

流式响应

设置 "stream": true 后，响应将以 Server-Sent Events (SSE) 格式逐步返回。每个 chunk 的 object 为 "chat.completion.chunk"，内容通过 delta 字段增量传递。

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aideskapp.com/v1",
    api_key="sk-aidesk-YOUR_KEY"
)

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

推理模式

启用推理后，模型会在回答前进行深度思考，适用于数学、逻辑等复杂任务。

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aideskapp.com/v1",
    api_key="sk-aidesk-YOUR_KEY"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "如果一个笼子里有兔子和鸡，共 35 个头、94 只脚，兔子有几只？"}
    ],
    extra_body={
        "aidesk_reasoning": {
            "enabled": True,
            "effort": "high"
        }
    }
)

# choices[0].message.reasoning_content 包含推理过程
print(response.choices[0].message.content)

常见错误码

HTTP 状态码	类型	说明
401	authentication_error	API Key 无效或已过期
403	permission_denied	余额不足或无权访问该模型
404	not_found	模型不存在或未启用
429	rate_limit_error	请求频率超限，请稍后重试
500	provider_error	上游 Provider 返回错误
503	service_unavailable	服务暂时不可用