Magick API 用户指南

兼容 Claude Messages API；支持 system、tools、图片内容和流式事件；成功响应为 Claude 原始协议。

路由：POST /v1/messages
协议形状与 Claude Messages API 对齐
成功响应为 Claude 原始 JSON 或 Claude 原始 SSE，不包 code / data

请求示例

curl https://api.magickapi.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2025-10-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "system": "你是一个专业的 AI 助手。",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "你好，世界"
      }
    ]
  }'

成功响应示例

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "你好！我是 Claude。"
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 18
  }
}

错误响应示例

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "请求参数无效"
  }
}

认证

`x-api-key`

类型：string
必填：是

`anthropic-version`

类型：string
必填：是

建议由 Claude SDK 或 Claude Code 按 Anthropic 协议正常发送。

常用参数

`model`

类型：string
必填：是

`system`

类型：string | array

Claude 的系统提示词是独立参数，不放在 messages 中。

`messages`

类型：array
必填：是

支持 user / assistant 角色。

`max_tokens`

类型：integer

`stream`

类型：boolean

传 true 时返回 Claude 原始 SSE 事件流。

`tools` / `tool_choice`

类型：array / object

当前项目会按 Claude 原生协议透传工具相关字段。

多模态与扩展能力

文本内容：支持
图片内容：支持
工具调用：支持
流式返回：支持
thinking / output_config / context_management：项目 DTO 已支持，可按 Claude 协议字段发送

兼容说明

如果你使用 Claude Code，请优先参考“开发工具 / Claude Code 使用指南”

Claude Messages

目录