8.9 KiB
8.9 KiB
AstrBot ImageStudio API 契约与前后端对接文档 v3.0
生成日期:2026-07-04
本文件给前端、后端、Codex、Hermes 共用。
目标:冻结 P0-P2 的前后端接口,避免 UI 和后端各自跑偏。
1. 基础路径
Standalone Web 直接调用:
/api/v1/plugins/extensions/astrbot_plugin_imagestudio/{endpoint}
Plugin Page 通过 Bridge 调用:
await window.AstrBotPluginPage.apiGet("{endpoint}")
await window.AstrBotPluginPage.apiPost("{endpoint}", payload)
2. 通用响应
成功
{
"ok": true,
"data": {},
"warnings": [],
"request_id": "req_xxx"
}
失败
{
"ok": false,
"error_code": "ERROR_CODE",
"message": "用户可理解错误",
"details": {},
"request_id": "req_xxx"
}
通用错误码
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
GET ui/bootstrap
响应:
{
"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
GET dashboard/summary
响应 data:
{
"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
GET profiles?keyword=&status=active&page=1&page_size=30
Create
POST profiles
请求:
{
"name": "莉娅",
"description": "银白发少女",
"base_prompt": "",
"appearance_prompt": "",
"style_prompt": "",
"negative_prompt": "",
"default_model_route": "image_low"
}
Quick Draft
POST profiles/quick-draft
请求:
{
"questionnaire": {
"name": "莉娅",
"identity": "魔法学院学生",
"personality": ["温柔", "安静"],
"hair_color": "银白色",
"hairstyle": "长发",
"eye_color": "蓝色",
"style": "二次元厚涂",
"clothing_keywords": ["白色上衣", "蓝色短裙"]
}
}
响应 data:
{
"draft_id": "draft_xxx",
"profile_preview": {
"name": "莉娅",
"base_prompt": "...",
"appearance_prompt": "...",
"style_prompt": "...",
"negative_prompt": "..."
}
}
Detail / Update / Delete
GET profiles/{profile_id}
PUT profiles/{profile_id}
DELETE profiles/{profile_id}
6. Workflows
List by Profile
GET profiles/{profile_id}/workflows
Create
POST profiles/{profile_id}/workflows
请求:
{
"workflow_type": "single_image",
"display_name": "单图流 2026-07-04",
"mode": "quick"
}
Detail
GET workflows/{workflow_id}
Start / Cancel / Archive
POST workflows/{workflow_id}/start
POST workflows/{workflow_id}/cancel
POST workflows/{workflow_id}/archive
7. Nodes
List
GET workflows/{workflow_id}/nodes
Generate
POST nodes/{node_id}/generate
请求:
{
"prompt_patch": "衣服改成白色衬衫",
"material_ids": ["mat_001"],
"model_route": "image_low",
"count": 4,
"aspect_ratio": "3:4",
"quality": "low"
}
响应 data:
{
"task_id": "task_xxx",
"node_status": "queued"
}
Select Image
POST nodes/{node_id}/select-image
请求:
{
"image_id": "img_001"
}
8. Images
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:
{
"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
GET material-categories
POST material-categories
PUT material-categories/{category_id}
DELETE material-categories/{category_id}
系统分类 seed:
[
{"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
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:
file=<image>
category_id=cat_upper
响应 data:
{
"material_id": "mat_001",
"status": "pending_recognition",
"image_url": "...",
"thumbnail_url": "..."
}
Confirm
{
"display_name": "白色短袖衬衫",
"prompt": "white short-sleeve blouse, clean collar",
"negative_prompt": "body, face, background",
"tags": ["上衣", "白色", "短袖"]
}
11. Wardrobe
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
{
"material_id": "mat_001",
"wardrobe_category": "上衣",
"tags": ["夏季", "白色", "清爽"],
"season": "summer",
"style": "daily"
}
Match
{
"keywords": ["夏季", "白色"],
"scene": "daily",
"weather": "sunny"
}
12. private_companion Integration
POST integrations/private-companion/daily-outfit
Header:
X-ImageStudio-Integration-Token: ***
请求:
{
"profile_id": "profile_001",
"character_name": "莉娅",
"scene": "daily",
"mood": "relaxed",
"weather": "sunny",
"keywords": ["夏季", "白色", "清爽"],
"request_source": "astrbot_plugin_private_companion"
}
响应:
{
"matched": true,
"selected_materials": [],
"final_prompt": "...",
"job_id": "task_xxx"
}
13. Jobs
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
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
15. Settings
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
16. Media
GET media/sign?uri=storage://...
GET media/fetch?token=...
禁止前端直接传真实路径。
17. SSE
GET events/stream?event_type=&limit=50
事件样例:
event: image.created
data: {"image_id":"img_001","node_id":"node_001"}
18. P0 接口冻结清单
P0 必须先实现:
ui/bootstrap
ui/actions
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 暂不强制实现:
api-discovery/probe-model
assets/import-pack
storage/migrate
advanced review policy editor
dead letter batch retry