API 文档

创建图片或视频任务时传入 webhook，任务进入终态后就会收到回调。

配置回调

{
  "model": "YOUR_MODEL_ID",
  "prompt": "任务提示词",
  "webhook": {
    "url": "https://your-app.example.com/webhooks/piccc",
    "secret": "replace-with-a-random-secret"
  }
}

• url 必须是 HTTPS 地址。
• secret 建议使用足够长的随机字符串，并保存在服务端。
• 不同环境使用不同的 URL 和 secret。

回调内容

任务成功：

{
  "type": "task.completed",
  "task": {
    "task_id": "task_xxx",
    "type": "image",
    "status": "completed",
    "progress": 100,
    "cost": 20,
    "error": null,
    "outputs": []
  }
}

失败和取消对应 task.failed、task.cancelled。

验证签名

配置了 secret 后，请求头会包含：

X-Piccc-Signature: sha256=<hex-hmac-sha256>

签名使用 secret 对原始 HTTP body 字符串计算 HMAC-SHA256。必须先保留原始 body，再解析 JSON；重新序列化后的 JSON 不能用于验签。

Node.js 示例：

import crypto from 'node:crypto'

export function verifyPicccSignature(secret, rawBody, signatureHeader) {
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')}`

  const expectedBuffer = Buffer.from(expected)
  const receivedBuffer = Buffer.from(String(signatureHeader || ''))

  return expectedBuffer.length === receivedBuffer.length
    && crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
}

验签失败时返回 401 或 400，不要继续处理任务结果。

先返回 2xx，再做耗时工作

验签、记录事件后尽快返回 2xx。下载文件、写入业务数据库、发送通知等耗时操作放进你自己的队列。

开放 API 对失败投递使用指数退避，最多尝试 12 次。同一任务状态可能被重复发送，接收端必须支持幂等处理。

可以使用下面的组合作为幂等键：

task.task_id + ":" + task.status

保存处理记录后再执行后续业务。收到相同幂等键时直接返回 200。

回调失败时补查

如果一段时间没有收到回调，使用 GET /v1/tasks/:id 查询任务。WebHook 用于通知，任务查询接口才是补查状态的入口。