File size: 3,976 Bytes
8ede856 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | ---
outline: deep
---
# AstrBot HTTP API
从 v4.18.0 开始，AstrBot 提供基于 API Key 的 HTTP API，开发者可以通过标准 HTTP 请求访问核心能力。
## 快速开始
1. 在 WebUI - 设置中创建 API Key。
2. 在请求头中携带 API Key：
```http
Authorization: Bearer abk_xxx
```
也支持：
```http
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. 纯文本格式
```json
{
"message": "Hello"
}
```
### 2. 消息段数组格式
```json
{
"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）。
```json
{
"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`。
```json
{
"umo": "webchat:FriendMessage:openapi_probe",
"message": [
{ "type": "plain", "text": "这是主动消息" },
{ "type": "image", "attachment_id": "9a2f8c72-e7af-4c0e-b352-222222222222" }
]
}
```
## 示例
```bash
curl -N 'http://localhost:7860/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
|