任务管理

查询任务状态

查询账户所属生成任务的状态、积分结算、结果或失败信息。

接口

GET/api/v1/developer/generations/{generation_id}

鉴权与 Scope

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

Scope: generations:read

仅可读取当前 App 及凭据 owner 的任务。非终态按 poll_after_ms 查询；succeeded、failed 或 cancelled 后停止。空字段省略，正式响应不包含匿名 quota。

请求参数

字段	类型	必填	说明
`generation_id`	UUID (path)	是	创建任务返回的标识；无 request body。

curl --request GET \
  --url 'https://api.perchanceai.art/api/v1/developer/generations/{generation_id}' \
  --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": "queued",
    "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:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

查询任务状态

接口

鉴权与 Scope

请求参数

响应 HTTP 200

相关错误