From d98e58adfa132bb9308c6e7fbd77a914952edb5f Mon Sep 17 00:00:00 2001
From: inman <inman@nianxx.com>
Date: Mon, 8 Jun 2026 11:24:54 +0800
Subject: [PATCH] docs: update public api docs

---
 app/api/v1/openapi.json/route.ts | 17 ++++++++++++++---
 docs/API.md                      | 25 +++++++++++++++++++------
 2 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/app/api/v1/openapi.json/route.ts b/app/api/v1/openapi.json/route.ts
index 47eb9d3..bb58500 100644
--- a/app/api/v1/openapi.json/route.ts
+++ b/app/api/v1/openapi.json/route.ts
@@ -142,10 +142,21 @@ export async function GET(request: Request) {
         },
         WebhookPayload: {
           type: "object",
-          required: ["event", "job"],
+          required: ["jobId", "status", "capability", "outputAssetIds", "updatedAt"],
           properties: {
-            event: { type: "string", example: "generation.succeeded" },
-            job: { $ref: "#/components/schemas/GenerationJob" }
+            jobId: { type: "string", example: "job_mpqe3wtt_12ed738079" },
+            status: { $ref: "#/components/schemas/GenerationStatus" },
+            capability: { $ref: "#/components/schemas/GenerationCapability" },
+            outputAssetIds: { type: "array", items: { type: "string" } },
+            error: {
+              type: "object",
+              properties: {
+                code: { oneOf: [{ type: "string" }, { type: "number" }] },
+                message: { type: "string" },
+                retryable: { type: "boolean" }
+              }
+            },
+            updatedAt: { type: "string", format: "date-time" }
           }
         }
       }
diff --git a/docs/API.md b/docs/API.md
index f3cf403..f14f908 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -79,6 +79,8 @@ curl -X POST https://你的域名/api/v1/jobs \
 }
 ```
 
+新建任务返回 `202`；如果命中相同 `Idempotency-Key` 的已创建任务，返回 `200` 且 `reused: true`。
+
 ### 支持的 capability
 
 | capability | 说明 |
@@ -111,6 +113,16 @@ curl -H "Authorization: Bearer <API_KEY>" \
 - `limit`：`1` 到 `200`
 - `before`：ISO 时间，用于翻页
 
+取消任务：
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <API_KEY>" \
+  https://你的域名/api/v1/jobs/job_xxx/cancel
+```
+
+仅排队中或运行中的任务会被置为 `cancelled`；已进入终态的任务会原样返回。
+
 ## 获取输出资产
 
 任务成功后，`job.outputAssetIds` 会包含输出资产 ID。
@@ -248,15 +260,16 @@ Idempotency-Key: <业务唯一请求ID>
 
 ```json
 {
-  "event": "generation.succeeded",
-  "job": {
-    "id": "job_xxx",
-    "status": "succeeded",
-    "outputAssetIds": ["asset_xxx"]
-  }
+  "jobId": "job_xxx",
+  "status": "succeeded",
+  "capability": "image.generate",
+  "outputAssetIds": ["asset_xxx"],
+  "updatedAt": "2026-06-08T12:00:00.000Z"
 }
 ```
 
+如果任务失败，payload 会包含 `error`。
+
 如果服务端配置了：
 
 ```env