任务管理

取消任务

请求协作取消账户所属生成任务，并查询真实最终状态。

接口

POST/api/v1/developer/generations/{generation_id}/cancel

鉴权与 Scope

Authorization: Bearer <credential>；仅接受正式账户 API Key / OAuth。

Scope: generations:write

取消是协作请求。排队且未分发的任务可能立即取消；运行中的任务仍可能返回 running。不保证立即终止或全额退款。继续查询最终 status 与 charged_credits。

无需 request body 或 Idempotency-Key。响应与任务查询使用相同 GenerationResponse；示例表示分发前成功取消的任务。

请求参数

字段	类型	必填	说明
`generation_id`	UUID (path)	是	账户所属任务标识。

curl --request POST \
  --url 'https://api.perchanceai.art/api/v1/developer/generations/{generation_id}/cancel' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>'

响应 HTTP 200

以下为说明响应结构的示例，并非实时 API 响应。示例数值和 USD 不代表固定定价或资金余额。空字段省略。

REST 成功响应为 success、code、message、request_id 和 data；下表描述 data。

字段	类型	必填	说明
`generation_id`	UUID	是	凭据所属账户及 App 的持久任务标识。
`status`	string	是	持续查询直到 succeeded、failed 或 cancelled；请求被接受不代表完成。
`model_key / modality / operation`	string	是	所选模型、image/video 模态及公开 operation。
`created_at / updated_at`	ISO UTC string	是	UTC 时间。
`completed_at`	ISO UTC string	否	存在时表示完成时间。
`poll_after_ms`	integer	否	非终态建议轮询间隔（当前 2000）；终态省略。
`estimated_credits / reserved_credits / charged_credits`	integer	是	账户积分估价、预扣及实际扣除。
`outputs`	object[]	是	media_id、media_type、url，以及可选 width、height、duration_ms。
`error`	object	否	任务失败信息：code、message、retryable；无错误时省略。
`client_trace_id`	string	否	提供时回传客户端关联标识。

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "cancelled",
    "model_key": "<model_key_from_catalog>",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:01.000Z",
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": [],
    "completed_at": "2026-10-14T00:00:01.000Z"
  }
}

取消任务

接口

鉴权与 Scope

请求参数

响应 HTTP 200

相关错误