Qingpu AI 工具 API
本文档说明 Qingpu 主题下新增的通用 AI 工具接口。这些接口统一复用 qingpu_tasks 任务账本与 qingpu_assets 资产表,不再为单个工具页单独拆任务系统。
总览
- 主题私有接口统一放在
/api/qingpu/** - 异步任务统一写入
qingpu_tasks - 生成结果统一落到
qingpu_assets,因此会自动出现在“我的创作”
1. 提交文本生图任务
- 请求地址:
/api/qingpu/tools/text-to-image/generate - 请求方法:
POST - 权限要求: 已登录用户或 Bearer 租户 Key
请求体
{
"prompt": "赛博朋克雨夜街道,霓虹倒影,电影感构图",
"negativePrompt": "模糊,重复,低质量",
"referenceUrl": "https://example.com/reference.png",
"modelName": "Flux.1 Pro",
"size": "1792x1024",
"quality": "high",
"profileId": "imgp_demo",
"format": "PNG",
"steps": 30,
"modePreset": "Quality"
}
成功响应
{
"code": 0,
"data": {
"taskId": 123,
"productId": "tool:tool:text-to-image",
"scope": "tool:text-to-image",
"enqueued": true,
"reason": null
}
}
说明
- 如果同一幂等键对应的任务已经在排队或执行中,
taskId可能为空,此时前端应改为轮询共享任务列表。 size、quality、profileId会覆盖用户在 Qingpu 设置页保存的默认图像生成配置。- 服务端会把
prompt、toolLabel、source等信息写入qingpu_assets.meta,供“我的创作”展示。
2. 轮询 Qingpu 共享任务
- 请求地址:
/api/qingpu/tasks - 请求方法:
GET - 权限要求: 已登录用户或 Bearer 租户 Key
查询参数
scope(可选): 按任务 payload 里的作用域过滤,例如tool:text-to-imagetype(可选): 按任务类型过滤,例如tool_image_generatelimit(可选): 返回条数,默认20,最大100
成功响应
{
"code": 0,
"data": {
"active": true,
"items": [
{
"id": 123,
"type": "tool_image_generate",
"productId": "tool:tool:text-to-image",
"title": "赛博朋克雨夜街道",
"scope": "tool:text-to-image",
"status": "running",
"progress": 45,
"stage": "tool-image:queued",
"error": null,
"resultUrl": null,
"resultAssetId": null,
"attempts": 0,
"updatedAt": "2026-07-23T02:01:23.000Z"
}
]
}
}
说明
active=true表示当前过滤条件下至少还有一条queued/running任务。- 任务成功后,
resultUrl与resultAssetId会被填充。 - 铺货工作台任务与工具页任务共用同一张账本,但可以通过
scope或type在前端隔离展示。