Chat Completions API

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

完全兼容 OpenAI Chat Completions 格式，可直接替换 base_url 使用。 支持多轮对话、流式输出、推理模式和联网搜索等功能。

POST https://api.aideskapp.com/v1/chat/completions

用 AI 编程助手接入？

一键复制本页文档的纯文本版，粘贴给 Claude Code、Cursor、ChatGPT 等大模型，让它照着帮你写接入代码。

核心请求参数

  • modelstring必填
    模型 ID，如 "claude-sonnet-5-5"、"gemini-3.8-flash"
  • messagesarray必填
    对话消息数组，每条含 role（system/user/assistant）和 content
  • temperaturefloat可选
    采样温度，0.0 - 2.0。值越高输出越随机，默认由模型决定
  • top_pfloat可选
    核采样参数，0.0 - 1.0，默认 1.0
  • max_tokensinteger可选
    最大生成 token 数，默认由模型决定
  • streamboolean可选
    是否启用流式响应，默认 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-5-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    temperature=0.7,
    max_tokens=500
)

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

响应字段说明

  • idstring
    补全的唯一标识符
  • objectstring
    固定为 "chat.completion"
  • createdinteger
    创建时间的 Unix 时间戳
  • modelstring
    生成补全时使用的模型 ID
  • choicesarray
    补全选项列表，每项含 message 和 finish_reason
  • choices[].messageobject
    包含 role、content，推理模型还有 reasoning_content
  • usageobject
    Token 用量：prompt_tokens、completion_tokens、total_tokens、reasoning_tokens、cached_tokens
  • providerstring
    实际处理请求的提供商标识
  • aidesk_kb_contextarray
    知识库检索上下文（启用 kb_search 时返回）
  • aidesk_web_contextarray
    联网搜索上下文（启用 web_search 时返回）

响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1746528000,
  "model": "claude-sonnet-5-5",
  "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": "anthropic"
}

流式响应

设置 "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-5-5",
    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-5-5",
    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)

常见错误码

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