zh dev openapi

AstrBot HTTP API

从 v4.18.0 开始，AstrBot 提供基于 API Key 的 HTTP API，开发者可以通过标准 HTTP 请求访问核心能力。

快速开始

1. 在 WebUI - 设置中创建 API Key。
2. 在请求头中携带 API Key：

Authorization: Bearer abk_xxx

也支持：

X-API-Key: abk_xxx

3. 对于对话接口，username 为必填参数：

• POST /api/v1/chat：请求体必须包含 username
• GET /api/v1/chat/sessions：查询参数必须包含 username

Scope 权限说明

创建 API Key 时可配置 scopes。每个 scope 控制可访问的接口范围：

Scope	作用	可访问接口
chat	调用对话能力、查询对话会话	POST /api/v1/chat、GET /api/v1/chat/sessions
config	获取可用配置文件列表	GET /api/v1/configs
file	上传附件文件，获取 attachment_id	POST /api/v1/file
im	主动发 IM 消息、查询 bot/platform 列表	POST /api/v1/im/message、GET /api/v1/im/bots

如果 API Key 未包含目标接口所需 scope，请求会返回 403 Insufficient API key scope。

常用接口

对话类

调用 AstrBot 内建的 Agent 进行对话交互。支持插件调用、工具调用等能力，与 IM 端对话能力一致。

• POST /api/v1/chat：发送对话消息（SSE 流式返回，不传 session_id 会自动创建 UUID）
• GET /api/v1/chat/sessions：分页获取指定 username 的会话
• GET /api/v1/configs：获取可用配置文件列表

文件上传

• POST /api/v1/file：上传附件

IM 消息发送

• POST /api/v1/im/message：按 UMO 主动发消息
• GET /api/v1/im/bots：获取 bot/platform ID 列表

message 字段格式（重点）

POST /api/v1/chat 和 POST /api/v1/im/message 的 message 字段支持两种格式：

1. 字符串：纯文本消息
2. 数组：消息段（message chain）

1. 纯文本格式

{
  "message": "Hello"
}

2. 消息段数组格式

{
  "message": [
    { "type": "plain", "text": "请看这个文件" },
    { "type": "file", "attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111" }
  ]
}

支持的 type：

type	必填字段	可选字段	说明
plain	text	-	文本段
reply	message_id	selected_text	引用回复某条消息
image	attachment_id	-	图片附件段
record	attachment_id	-	音频附件段
file	attachment_id	-	通用文件段
video	attachment_id	-	视频附件段

• reply 消息段目前仅适配 /api/v1/chat，不适用于 POST /api/v1/im/message。

说明：

• attachment_id 来自 POST /api/v1/file 上传结果。
• reply 不能单独作为唯一内容，至少需要一个有实际内容的段（如 plain/image/file/...）。
• 仅 reply 或空内容会返回错误。

Chat API 的 message 用法

POST /api/v1/chat 额外需要 username，可选 session_id（不传会自动创建 UUID）。

{
  "username": "alice",
  "session_id": "my_session_001",
  "message": [
    { "type": "plain", "text": "帮我总结这个 PDF" },
    { "type": "file", "attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111" }
  ],
  "enable_streaming": true
}

IM Message API 的 message 用法

POST /api/v1/im/message 需要 umo + message。

{
  "umo": "webchat:FriendMessage:openapi_probe",
  "message": [
    { "type": "plain", "text": "这是主动消息" },
    { "type": "image", "attachment_id": "9a2f8c72-e7af-4c0e-b352-222222222222" }
  ]
}

示例

curl -N 'http://localhost:6185/api/v1/chat' \
  -H 'Authorization: Bearer abk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello","username":"alice"}'

完整 API 文档

交互式 API 文档请查看：

• https://docs.astrbot.app/scalar.html