Messages API

使用 Anthropic Messages API 进行对话生成，兼容官方 Anthropic 格式。

Messages API 完全兼容 Anthropic 官方 /v1/messages 格式， 可直接搭配官方 anthropic SDK、Claude Code 等 Anthropic 客户端使用，只需替换 base_url 与 API Key 即可。 支持多轮对话、流式输出、扩展思考（Extended Thinking）以及工具调用（Tool Use）。

除 Claude 系列外，该端点同样可路由到 GPT、Gemini、DeepSeek 等模型；平台会自动在 Anthropic 格式与上游 Provider 之间完成协议转换。

用 AI 编程助手接入？

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

端点与鉴权

POST https://api.aideskapp.com/v1/messages

通过请求头进行鉴权，与 Anthropic 官方保持一致：

  • x-api-keysk-aidesk-YOUR_KEY
    平台 API Key（也可用 Authorization: Bearer 传入）
  • anthropic-version2023-06-01
    Anthropic API 版本，建议固定填写
  • content-typeapplication/json
    请求体为 JSON

核心请求参数

  • modelstring必填
    模型 ID，如 "claude-sonnet-5-5"、"gpt-6.1-sol"、"gemini-3.8-flash"
  • messagesarray必填
    对话消息数组，每条含 role（user/assistant）和 content（字符串或内容块数组）
  • max_tokensinteger必填
    本次生成的最大 token 数
  • systemstring | array可选
    系统提示，可为字符串或内容块数组
  • temperaturefloat可选
    采样温度，0.0 - 1.0，默认由模型决定
  • top_pfloat可选
    核采样参数，0.0 - 1.0
  • stop_sequencesarray可选
    自定义停止序列，命中后停止生成
  • streamboolean可选
    是否启用 SSE 流式响应，默认 false
  • toolsarray可选
    工具定义列表，启用 Tool Use
  • tool_choiceobject | string可选
    工具选择策略，如 {"type": "auto"}
  • thinkingobject可选
    扩展思考配置，如 {"type": "enabled", "budget_tokens": 10000}

请求示例

使用官方 Anthropic Python SDK：

from anthropic import Anthropic

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

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

print(message.content[0].text)

或使用 cURL：

curl https://api.aideskapp.com/v1/messages \
  -H "x-api-key: sk-aidesk-YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 500,
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

响应字段说明

  • idstring
    消息的唯一标识符，如 msg_xxx
  • typestring
    固定为 "message"
  • rolestring
    固定为 "assistant"
  • contentarray
    内容块数组，每块含 type：text / thinking / tool_use
  • modelstring
    实际使用的模型 ID
  • stop_reasonstring
    end_turn / max_tokens / stop_sequence / tool_use
  • stop_sequencestring
    命中的停止序列，未命中为 null
  • usageobject
    Token 用量：input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens

响应示例

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "你好！我是 AI 助手，有什么可以帮你的吗？"
    }
  ],
  "model": "claude-sonnet-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 18,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

流式响应

设置 "stream": true 后，响应以 Server-Sent Events (SSE) 返回， 事件类型依次为 message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。文本通过 content_block_delta 的 delta.text 增量传递。

from anthropic import Anthropic

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

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

扩展思考（Extended Thinking）

通过 thinking 参数开启深度思考，模型会先输出 thinking 内容块再给出回答，适用于数学、逻辑等复杂任务。

from anthropic import Anthropic

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

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {"role": "user", "content": "如果一个笼子里有兔子和鸡，共 35 个头、94 只脚，兔子有几只？"}
    ],
)

for block in message.content:
    if block.type == "thinking":
        print("【思考】", block.thinking)
    elif block.type == "text":
        print("【回答】", block.text)

Token 计数

调用 POST /v1/messages/count_tokens 可在不实际生成内容的情况下预估输入 Token 数， 请求体与 Messages API 一致（无需 max_tokens）。

curl https://api.aideskapp.com/v1/messages/count_tokens \
  -H "x-api-key: sk-aidesk-YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

# => {"input_tokens": 25}

常见错误码

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