API 文档

图片和视频任务创建后会先返回 queued。保存响应中的 task_id，再查询任务状态。

查询单个任务

curl https://api.picccai.cn/v1/tasks/task_xxx \
  -H "Authorization: Bearer $PICCC_API_KEY"

完成后的图片任务示例：

{
  "task_id": "task_xxx",
  "type": "image",
  "model": "image-model-id",
  "status": "completed",
  "progress": 100,
  "cost": 20,
  "error": null,
  "outputs": [
    {
      "id": "file_xxx",
      "url": "https://cdn.example.com/output.png",
      "thumbnail_url": "https://cdn.example.com/thumb.png",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024,
      "duration_seconds": null
    }
  ],
  "created_at": 1783728000000,
  "updated_at": 1783728060000,
  "completed_at": 1783728060000
}

任务状态

状态	是否终态	说明
queued	否	已进入队列，等待处理。
running	否	Worker 已开始执行。
processing	否	上游正在生成或结果正在处理。
completed	是	生成成功，从 outputs 读取文件。
failed	是	生成失败，从 error 读取错误信息。
cancelled	是	任务已取消。

客户端遇到未知的非终态值时，应继续等待，不要直接当作失败。

轮询示例

下面的 Node.js 示例从 2 秒开始轮询，最长等待 10 分钟：

const baseUrl = 'https://api.picccai.cn'
const apiKey = process.env.PICCC_API_KEY

async function waitForTask(taskId) {
  const deadline = Date.now() + 10 * 60 * 1000
  let delay = 2000

  while (Date.now() < deadline) {
    const response = await fetch(`${baseUrl}/v1/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    })

    if (!response.ok) {
      throw new Error(`Task query failed: ${response.status} ${await response.text()}`)
    }

    const task = await response.json()
    if (['completed', 'failed', 'cancelled'].includes(task.status)) return task

    await new Promise((resolve) => setTimeout(resolve, delay))
    delay = Math.min(10000, Math.round(delay * 1.5))
  }

  throw new Error('Task polling timed out')
}

生产环境更适合使用 WebHook。轮询可以作为回调异常时的补查手段。

查询任务列表

curl "https://api.picccai.cn/v1/tasks?type=image&status=completed&page=1&page_size=20" \
  -H "Authorization: Bearer $PICCC_API_KEY"

查询参数：

参数	说明
type	可选，image 或 video。不传时同时查询两类任务。
status	可选，按任务状态过滤。
page	页码，默认 1。
page_size	每页数量，默认 20，最大 100。

列表接口不返回总数。当 items.length 小于 page_size 时，可以停止翻页。

任务列表按账号查询，可能同时包含该账号在 Piccc AI 主站创建的图片和视频任务。