# 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= 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 ``` --- ## 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 ``` --- ## 16. Media ```http GET media/sign?uri=storage://... GET media/fetch?token=... ``` 禁止前端直接传真实路径。 --- ## 17. SSE ```http GET events/stream?event_type=&limit=50 ``` 事件样例: ```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 ```