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_taskstable instead of creating tool-specific task ledgers. - Generated outputs are written into
qingpu_assetsso 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
taskIdis nullable when the same dedupe key is already queued or running.size,quality, andprofileIdoverride the user's saved Qingpu image model defaults.- The server persists tool metadata like
prompt,toolLabel, andsourceintoqingpu_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 astool:text-to-imagetype(optional): filter by task type, such astool_image_generatelimit(optional): number of rows to return, default20, max100
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=truemeans at least one queued or running task matches the filter.resultUrlandresultAssetIdare populated after the task succeeds.- Existing listing workbench tasks and tool tasks share the same ledger, but can be separated by
scopeortype.