---
title: "Qingpu AI Tools"
canonical_url: "https://ainode.run/docs/qingpu-ai-tools"
type: "doc"
locale: "en"
description: "Theme-private async AI tool APIs for text-to-image and shared task polling"
---

# Qingpu AI Tools
> Theme-private async AI tool APIs for text-to-image and shared task polling

# 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

```json
{
  "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

```json
{
  "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

```json
{
  "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`.
