astrbot_plugin_imagestudio/imagestudio_api_contract_v3_ui_adjusted.md

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
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