astrbot_plugin_imagestudio/imagestudio_api_contract_v3_ui_adjusted.md

587 行
8.9 KiB
Markdown

2026-07-04 22:51:52 +08:00
# 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?status=&workflow_id=&profile_id=&node_id=&limit=50
GET logs/workflows?workflow_id=&action=&node_id=&branch_name=&limit=50
GET logs/errors?source=&status=&limit=50
GET logs/integrations?integration_name=&action=&status=&limit=50
GET security/audit-logs?action=&target_type=&actor_id=&limit=50
2026-07-04 22:51:52 +08:00
```
---
## 15. Settings
```http
GET settings/schema
GET settings/current
POST settings/validate
POST settings/diff
POST settings/save
POST settings/reload
GET settings/export
POST settings/import
GET settings/snapshots?limit=20
GET settings/snapshots/{snapshot_id}
POST settings/rollback
2026-07-04 22:51:52 +08:00
```
---
## 16. Media
```http
GET media/sign?uri=storage://...
GET media/fetch?token=...
```
禁止前端直接传真实路径。
---
## 17. SSE
```http
2026-07-05 16:23:47 +08:00
GET events/stream?event_type=&limit=50
2026-07-04 22:51:52 +08:00
```
事件样例:
```text
event: image.created
data: {"image_id":"img_001","node_id":"node_001"}
```
---
## 18. P0 接口冻结清单
P0 必须先实现:
```text
ui/bootstrap
ui/actions
2026-07-04 22:51:52 +08:00
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
```