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-image
  • type(可选): 按任务类型过滤,例如 tool_image_generate
  • limit(可选): 返回条数,默认 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 在前端隔离展示。