581 行
8.5 KiB
Markdown
581 行
8.5 KiB
Markdown
|
|
# AstrBot ImageStudio API 契约与前后端对接文档 v3.0
|
|||
|
|
|
|||
|
|
> 生成日期:2026-07-04
|
|||
|
|
> 本文件给前端、后端、Codex、Hermes 共用。
|
|||
|
|
> 目标:冻结 P0-P2 的前后端接口,避免 UI 和后端各自跑偏。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 基础路径
|
|||
|
|
|
|||
|
|
Standalone Web 直接调用:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
/api/v1/plugins/extensions/astrbot_plugin_imagestudio/{endpoint}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Plugin Page 通过 Bridge 调用:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
await window.AstrBotPluginPage.apiGet("{endpoint}")
|
|||
|
|
await window.AstrBotPluginPage.apiPost("{endpoint}", payload)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 通用响应
|
|||
|
|
|
|||
|
|
### 成功
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"ok": true,
|
|||
|
|
"data": {},
|
|||
|
|
"warnings": [],
|
|||
|
|
"request_id": "req_xxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 失败
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"ok": false,
|
|||
|
|
"error_code": "ERROR_CODE",
|
|||
|
|
"message": "用户可理解错误",
|
|||
|
|
"details": {},
|
|||
|
|
"request_id": "req_xxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 通用错误码
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
UNAUTHORIZED
|
|||
|
|
FORBIDDEN
|
|||
|
|
VALIDATION_FAILED
|
|||
|
|
RESOURCE_NOT_FOUND
|
|||
|
|
CONFIG_REVISION_CONFLICT
|
|||
|
|
TASK_NOT_RETRYABLE
|
|||
|
|
TASK_NOT_CANCELABLE
|
|||
|
|
MODEL_CAPABILITY_UNCONFIRMED
|
|||
|
|
MODEL_CAPABILITY_UNSUPPORTED
|
|||
|
|
STORAGE_WRITE_FAILED
|
|||
|
|
MEDIA_NOT_FOUND
|
|||
|
|
UPLOAD_TOO_LARGE
|
|||
|
|
UNSUPPORTED_FILE_TYPE
|
|||
|
|
INTEGRATION_TOKEN_INVALID
|
|||
|
|
UNKNOWN_ERROR
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. UI Bootstrap
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET ui/bootstrap
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"plugin_name": "astrbot_plugin_imagestudio",
|
|||
|
|
"display_name": "ImageStudio",
|
|||
|
|
"plugin_version": "3.0.0",
|
|||
|
|
"dashboard_user": "admin",
|
|||
|
|
"permissions": {
|
|||
|
|
"can_read": true,
|
|||
|
|
"can_write": true,
|
|||
|
|
"can_manage_config": true,
|
|||
|
|
"can_manage_materials": true,
|
|||
|
|
"can_retry_tasks": true
|
|||
|
|
},
|
|||
|
|
"feature_flags": {
|
|||
|
|
"quick_profile": true,
|
|||
|
|
"workspace": true,
|
|||
|
|
"material_library": true,
|
|||
|
|
"wardrobe": true,
|
|||
|
|
"api_discovery": true
|
|||
|
|
},
|
|||
|
|
"api_base": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Dashboard
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET dashboard/summary
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应 data:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"plugin_status": "running",
|
|||
|
|
"today_generation_count": 0,
|
|||
|
|
"active_profiles": 0,
|
|||
|
|
"queue": {
|
|||
|
|
"pending": 0,
|
|||
|
|
"running": 0,
|
|||
|
|
"failed": 0,
|
|||
|
|
"dead_letter": 0
|
|||
|
|
},
|
|||
|
|
"storage": {
|
|||
|
|
"total_bytes": 0,
|
|||
|
|
"images_bytes": 0,
|
|||
|
|
"materials_bytes": 0,
|
|||
|
|
"temp_bytes": 0
|
|||
|
|
},
|
|||
|
|
"recent_jobs": [],
|
|||
|
|
"recent_images": []
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Profiles
|
|||
|
|
|
|||
|
|
### List
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET profiles?keyword=&status=active&page=1&page_size=30
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Create
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST profiles
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"name": "莉娅",
|
|||
|
|
"description": "银白发少女",
|
|||
|
|
"base_prompt": "",
|
|||
|
|
"appearance_prompt": "",
|
|||
|
|
"style_prompt": "",
|
|||
|
|
"negative_prompt": "",
|
|||
|
|
"default_model_route": "image_low"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Quick Draft
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST profiles/quick-draft
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"questionnaire": {
|
|||
|
|
"name": "莉娅",
|
|||
|
|
"identity": "魔法学院学生",
|
|||
|
|
"personality": ["温柔", "安静"],
|
|||
|
|
"hair_color": "银白色",
|
|||
|
|
"hairstyle": "长发",
|
|||
|
|
"eye_color": "蓝色",
|
|||
|
|
"style": "二次元厚涂",
|
|||
|
|
"clothing_keywords": ["白色上衣", "蓝色短裙"]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应 data:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"draft_id": "draft_xxx",
|
|||
|
|
"profile_preview": {
|
|||
|
|
"name": "莉娅",
|
|||
|
|
"base_prompt": "...",
|
|||
|
|
"appearance_prompt": "...",
|
|||
|
|
"style_prompt": "...",
|
|||
|
|
"negative_prompt": "..."
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Detail / Update / Delete
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET profiles/{profile_id}
|
|||
|
|
PUT profiles/{profile_id}
|
|||
|
|
DELETE profiles/{profile_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Workflows
|
|||
|
|
|
|||
|
|
### List by Profile
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET profiles/{profile_id}/workflows
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Create
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST profiles/{profile_id}/workflows
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"workflow_type": "single_image",
|
|||
|
|
"display_name": "单图流 2026-07-04",
|
|||
|
|
"mode": "quick"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Detail
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET workflows/{workflow_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Start / Cancel / Archive
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST workflows/{workflow_id}/start
|
|||
|
|
POST workflows/{workflow_id}/cancel
|
|||
|
|
POST workflows/{workflow_id}/archive
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Nodes
|
|||
|
|
|
|||
|
|
### List
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET workflows/{workflow_id}/nodes
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Generate
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST nodes/{node_id}/generate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"prompt_patch": "衣服改成白色衬衫",
|
|||
|
|
"material_ids": ["mat_001"],
|
|||
|
|
"model_route": "image_low",
|
|||
|
|
"count": 4,
|
|||
|
|
"aspect_ratio": "3:4",
|
|||
|
|
"quality": "low"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应 data:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"task_id": "task_xxx",
|
|||
|
|
"node_status": "queued"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Select Image
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST nodes/{node_id}/select-image
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"image_id": "img_001"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Images
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET nodes/{node_id}/images
|
|||
|
|
GET images/{image_id}
|
|||
|
|
POST images/{image_id}/select
|
|||
|
|
POST images/{image_id}/unselect
|
|||
|
|
POST images/{image_id}/archive
|
|||
|
|
DELETE images/{image_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应 data:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"image_id": "img_001",
|
|||
|
|
"thumbnail_url": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch?token=xxx",
|
|||
|
|
"image_url": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch?token=yyy",
|
|||
|
|
"positive_prompt": "...",
|
|||
|
|
"negative_prompt": "...",
|
|||
|
|
"model_used": "model_x",
|
|||
|
|
"seed": 123,
|
|||
|
|
"width": 1024,
|
|||
|
|
"height": 1536,
|
|||
|
|
"is_selected": true,
|
|||
|
|
"created_at": "2026-07-04T22:00:00+09:00"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. Material Categories
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET material-categories
|
|||
|
|
POST material-categories
|
|||
|
|
PUT material-categories/{category_id}
|
|||
|
|
DELETE material-categories/{category_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
系统分类 seed:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{"name": "画风", "parent_id": null},
|
|||
|
|
{"name": "发色", "parent_id": null},
|
|||
|
|
{"name": "发型", "parent_id": null},
|
|||
|
|
{"name": "上衣", "parent_id": null},
|
|||
|
|
{"name": "下装", "parent_id": null},
|
|||
|
|
{"name": "连衣裙", "parent_id": null},
|
|||
|
|
{"name": "袜子", "parent_id": null},
|
|||
|
|
{"name": "鞋子", "parent_id": null},
|
|||
|
|
{"name": "配饰", "parent_id": null},
|
|||
|
|
{"name": "头饰", "parent_name": "配饰"},
|
|||
|
|
{"name": "胸饰", "parent_name": "配饰"},
|
|||
|
|
{"name": "腿饰", "parent_name": "配饰"}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Materials
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET materials?category_id=&keyword=&page=1&page_size=30
|
|||
|
|
POST materials
|
|||
|
|
GET materials/{material_id}
|
|||
|
|
PUT materials/{material_id}
|
|||
|
|
DELETE materials/{material_id}
|
|||
|
|
POST materials/upload
|
|||
|
|
POST materials/{material_id}/recognize
|
|||
|
|
POST materials/{material_id}/confirm
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Upload
|
|||
|
|
|
|||
|
|
multipart form:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
file=<image>
|
|||
|
|
category_id=cat_upper
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应 data:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"material_id": "mat_001",
|
|||
|
|
"status": "pending_recognition",
|
|||
|
|
"image_url": "...",
|
|||
|
|
"thumbnail_url": "..."
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Confirm
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"display_name": "白色短袖衬衫",
|
|||
|
|
"prompt": "white short-sleeve blouse, clean collar",
|
|||
|
|
"negative_prompt": "body, face, background",
|
|||
|
|
"tags": ["上衣", "白色", "短袖"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. Wardrobe
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET profiles/{profile_id}/wardrobe
|
|||
|
|
POST profiles/{profile_id}/wardrobe/import-material
|
|||
|
|
DELETE profiles/{profile_id}/wardrobe/items/{wardrobe_item_id}
|
|||
|
|
POST profiles/{profile_id}/wardrobe/match
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Import Material
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"material_id": "mat_001",
|
|||
|
|
"wardrobe_category": "上衣",
|
|||
|
|
"tags": ["夏季", "白色", "清爽"],
|
|||
|
|
"season": "summer",
|
|||
|
|
"style": "daily"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Match
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"keywords": ["夏季", "白色"],
|
|||
|
|
"scene": "daily",
|
|||
|
|
"weather": "sunny"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. private_companion Integration
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST integrations/private-companion/daily-outfit
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Header:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
X-ImageStudio-Integration-Token: ***
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请求:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"profile_id": "profile_001",
|
|||
|
|
"character_name": "莉娅",
|
|||
|
|
"scene": "daily",
|
|||
|
|
"mood": "relaxed",
|
|||
|
|
"weather": "sunny",
|
|||
|
|
"keywords": ["夏季", "白色", "清爽"],
|
|||
|
|
"request_source": "astrbot_plugin_private_companion"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"matched": true,
|
|||
|
|
"selected_materials": [],
|
|||
|
|
"final_prompt": "...",
|
|||
|
|
"job_id": "task_xxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 13. Jobs
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET jobs?status=&workflow_id=&profile_id=&page=1&page_size=30
|
|||
|
|
GET jobs/{task_id}
|
|||
|
|
POST jobs/{task_id}/cancel
|
|||
|
|
POST jobs/{task_id}/retry
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 14. Logs
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET logs/generation
|
|||
|
|
GET logs/workflows
|
|||
|
|
GET logs/errors
|
|||
|
|
GET logs/integrations
|
|||
|
|
GET security/audit-logs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 15. Settings
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET settings/schema
|
|||
|
|
GET settings/current
|
|||
|
|
POST settings/validate
|
|||
|
|
POST settings/diff
|
|||
|
|
POST settings/save
|
|||
|
|
POST settings/reload
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 16. Media
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET media/sign?uri=storage://...
|
|||
|
|
GET media/fetch?token=...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
禁止前端直接传真实路径。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 17. SSE
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
GET events/stream
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
事件样例:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
event: image.created
|
|||
|
|
data: {"image_id":"img_001","node_id":"node_001"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 18. P0 接口冻结清单
|
|||
|
|
|
|||
|
|
P0 必须先实现:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
ui/bootstrap
|
|||
|
|
dashboard/summary
|
|||
|
|
profiles GET/POST/GET_ONE/PUT
|
|||
|
|
profiles/quick-draft
|
|||
|
|
profiles/{profile_id}/workflows GET/POST
|
|||
|
|
workflows/{workflow_id}
|
|||
|
|
workflows/{workflow_id}/nodes
|
|||
|
|
nodes/{node_id}/generate
|
|||
|
|
nodes/{node_id}/images
|
|||
|
|
images/{image_id}
|
|||
|
|
images/{image_id}/select
|
|||
|
|
jobs
|
|||
|
|
jobs/{task_id}
|
|||
|
|
settings/schema
|
|||
|
|
settings/current
|
|||
|
|
storage/status
|
|||
|
|
media/sign
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
P0 暂不强制实现:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
api-discovery/probe-model
|
|||
|
|
assets/import-pack
|
|||
|
|
storage/migrate
|
|||
|
|
advanced review policy editor
|
|||
|
|
dead letter batch retry
|
|||
|
|
```
|