API 文档

QT Pixel 开放 API 接口，支持程序化访问和 MCP 工具对接

⚡快速开始

  1. 注册账号 获取 API Key
  2. 在用户后台 设置页面 查看你的 API Key
  3. 在请求头中添加 Authorization: Bearer YOUR_API_KEY
  4. 调用 API 接口创建像素画生成任务

🔐认证方式

所有 API 请求都需要在 HTTP 请求头中包含 API Key： 

Authorization: Bearer gpa_your_api_key_here

📡API 端点

POST /api/v1/generate

创建像素画生成任务

请求参数： 

{
  "prompt": "一只可爱的猫",
  "background": "transparent",  // 可选：transparent 或 white
  "force": false,               // 可选：是否强制生成（跳过缓存）
  "scale": 20,                  // 可选：缩放比例（默认 20）
  "email": "user@example.com",  // 可选：默认使用账号邮箱
  "send_email": true           // 可选：是否发送邮件通知
}

响应示例： 

{
  "task_id": 123,
  "status": "pending"
}

说明：当 force=false 且存在相似提示词时，返回 status: "duplicates_found" 及已有作品。

GET /api/v1/task/:id

查询任务状态和结果

查询参数：

  • include_base64 - 设为 "true" 可返回 base64 编码的图片数据

响应示例： 

{
  "id": 123,
  "prompt": "一只可爱的猫",
  "status": "completed",
  "image_path": "/static/gallery/123.png",
  "image_base64": "data:image/png;base64,...", // 仅当 include_base64=true
  "error_msg": "",                            // 失败时的错误信息
  "batch_id": null,                           // 批量任务 ID（如有）
  "created_at": "2026-01-27T12:00:00Z",
  "updated_at": "2026-01-27T12:00:30Z"
}
GET /api/v1/tasks

获取任务列表

查询参数：

  • status - 任务状态筛选（pending, processing, completed, failed）
  • page - 页码（默认 1）
  • include_base64 - 设为 "true" 返回 base64 图片（每次最多 10 张）

响应示例： 

{
  "tasks": [
    {
      "id": 123,
      "prompt": "...",
      "status": "completed",
      "image_path": "/static/gallery/123.png",
      "error_msg": "",
      "batch_id": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 20,
  "base64_limited": false  // true 表示超过 10 张图片的 base64 被截断
}
DELETE /api/v1/task/:id

删除指定任务

POST /api/v1/batch-generate NEW

批量生成多张像素画，支持精灵动画模式

请求参数： 

{
  "prompt": "一只可爱的猫",
  "mode": "walk",         // 可选：精灵模式（见下表）
  "count": 4,            // 数量（1-4），模式会自动设置
  "background": "transparent",
  "variations": true,    // 是否生成变体（未指定 mode 时）
  "scale": 20,           // 可选：缩放比例（默认 20）
  "send_email": false    // 可选：是否发送邮件通知
}

🎮 精灵动画模式：

模式 帧数 说明
walk 4 行走循环动画（左脚→站立→右脚→站立）
idle 2 待机呼吸动画
attack 3 攻击动画（蓄力→出击→恢复）
directions 4 4 方向视图（正面→背面→左侧→右侧）
variations 1-4 同一主题的风格变体
random 1-4 随机生成，无特殊指令（默认）

说明：使用精灵模式（walk/idle/attack/directions）时，count 参数会自动设置为该模式所需的帧数。

响应示例： 

{
  "batch_id": 1,
  "task_ids": [123, 124, 125, 126],
  "requested_count": 4,
  "status": "pending"
}
GET /api/v1/batch/:id NEW

查询批量任务状态和所有子任务

查询参数：

  • include_base64 - 设为 "true" 返回 base64 图片（每次最多 10 张）

响应示例： 

{
  "batch": {
    "id": 1,
    "prompt": "...",
    "mode": "walk",
    "status": "completed",
    "requested_count": 4,
    "generated_count": 4
  },
  "tasks": [
    {
      "id": 123,
      "status": "completed",
      "image_path": "/static/gallery/123.png",
      "batch_index": 1,
      "error_msg": ""
    }
    // ... 更多任务
  ],
  "completed_count": 3,
  "failed_count": 1,
  "total_count": 4,
  "base64_limited": false  // 当 include_base64=true 时
}
GET /api/v1/batches NEW

获取批量任务列表

查询参数：

  • page - 页码（默认 1）
GET /api/v1/task/:id/download-url

获取任务图片的签名临时下载链接

响应示例： 

{
  "download_url": "https://pixel.qingchencloud.com/api/download/123?sig=xxx&exp=1738000000",
  "expires_in": 3600  // 链接有效期 1 小时
}

说明：下载链接包含签名和过期时间，在有效期内可无需认证直接下载。

GET /api/v1/batch/:id/download

将批量任务中所有已完成的图片打包为 ZIP 下载

响应：

返回包含所有已完成图片的 ZIP 文件。文件按模式和序号命名（如 walk_1.png、walk_2.png）。

  • Content-Type: application/zip
  • Content-Disposition: attachment; filename=batch_1_walk.zip

📋状态码说明

状态 说明
pending 任务已创建，等待处理
processing 正在生成中
completed 生成成功
failed 生成失败

⚠️错误处理

HTTP 状态码

状态码 说明
200 请求成功
400 请求错误 - 参数无效
401 未授权 - API Key 无效
403 禁止访问 - 无权限
404 未找到 - 资源不存在
500 服务器错误 - 内部错误

错误响应格式 

{
  "error": "错误描述",
  "details": "详细信息（可选）"
}

🛡️ 内容安全拦截

当 AI 检测到提示词中可能包含敏感内容时，任务将失败并返回安全拦截错误。任务响应中的 error_msg 字段会包含原因。 

{
  "id": 123,
  "status": "failed",
  "error_msg": "⚠️ 生成失败: AI 拒绝处理此请求 (可能包含敏感内容)"
}

提示：避免使用包含暴力、成人内容、仇恨言论或其他潜在有害内容的提示词。

🔧MCP 工具集成

QT Pixel 提供 MCP (Model Context Protocol) 工具支持，可直接集成到 Claude、Cursor 等 AI 应用中。

配置方法： 

{
  "mcpServers": {
    "qtpixel": {
      "command": "npx",
      "args": ["-y", "@qingchencloud/qtpixel-mcp"],
      "env": {
        "QTPIXEL_API_KEY": "your_api_key_here",
        "QTPIXEL_API_BASE": "https://pixel.qingchencloud.com"
      }
    }
  }
}

可用工具：

  • create_pixel_art - 创建像素画
  • batch_generate - 批量生成（1-4张）
  • get_task_status - 查询任务状态
  • get_batch_status - 查询批量任务状态
  • list_my_artworks - 列出我的作品
📖 查看详细 MCP 配置指南

💻示例代码

cURL

curl -X POST https://pixel.qingchencloud.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一只可爱的猫"}'

Python

import requests

url = "https://pixel.qingchencloud.com/api/v1/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {"prompt": "一只可爱的猫"}

response = requests.post(url, json=data, headers=headers)
print(response.json())

JavaScript

const response = await fetch('https://pixel.qingchencloud.com/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: '一只可爱的猫'
  })
});

const data = await response.json();
console.log(data);

遇到问题？ 联系技术支持