Qingpu AI Tools API

This module documents the theme-private Qingpu AI tool APIs that reuse the shared qingpu_tasks ledger and qingpu_assets store.

Overview

  • Theme-private endpoints live under /api/qingpu/**.
  • Async jobs reuse the shared qingpu_tasks table instead of creating tool-specific task ledgers.
  • Generated outputs are written into qingpu_assets so they automatically appear in "My Creations".

1. Submit Text-to-Image Task

  • Endpoint: /api/qingpu/tools/text-to-image/generate
  • Method: POST
  • Authentication: Required (User Session or Bearer tenant key)

Request Body

{
  "prompt": "Cyberpunk city street at night, rainy neon reflections, cinematic framing",
  "negativePrompt": "blurry, duplicate, low quality",
  "referenceUrl": "https://example.com/reference.png",
  "modelName": "Flux.1 Pro",
  "size": "1792x1024",
  "quality": "high",
  "profileId": "imgp_demo",
  "format": "PNG",
  "steps": 30,
  "modePreset": "Quality"
}

Success Response

{
  "code": 0,
  "data": {
    "taskId": 123,
    "productId": "tool:tool:text-to-image",
    "scope": "tool:text-to-image",
    "enqueued": true,
    "reason": null
  }
}

Notes

  • taskId is nullable when the same dedupe key is already queued or running.
  • size, quality, and profileId override the user's saved Qingpu image model defaults.
  • The server persists tool metadata like prompt, toolLabel, and source into qingpu_assets.meta.

2. Poll Shared Qingpu Tasks

  • Endpoint: /api/qingpu/tasks
  • Method: GET
  • Authentication: Required (User Session or Bearer tenant key)

Query Parameters

  • scope (optional): filter by task payload scope, such as tool:text-to-image
  • type (optional): filter by task type, such as tool_image_generate
  • limit (optional): number of rows to return, default 20, max 100

Success Response

{
  "code": 0,
  "data": {
    "active": true,
    "items": [
      {
        "id": 123,
        "type": "tool_image_generate",
        "productId": "tool:tool:text-to-image",
        "title": "Cyberpunk city street at night",
        "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"
      }
    ]
  }
}

Notes

  • active=true means at least one queued or running task matches the filter.
  • resultUrl and resultAssetId are populated after the task succeeds.
  • Existing listing workbench tasks and tool tasks share the same ledger, but can be separated by scope or type.