Jobs
GET /v1/jobs/:id·GET /v1/jobs/:id/events·POST /v1/jobs/:id/cancel异步作业的状态、事件与取消
图片生成/改图提交后返回作业 ID。作业只能由提交它的用户访问。
作业状态#
queued → running → completed
↘ failed(重试耗尽)
↘ cancelled| 状态 | 含义 |
|---|---|
pending |
已入队(提交响应的 status) |
running |
worker 执行中 |
completed |
成功,artifacts 有产物 |
failed |
终态失败 |
cancelled |
客户端取消 |
GET /v1/jobs/:id#
GET /v1/jobs/123
Authorization: Bearer nx-...{
"id": 123,
"public_model": "nexith-image",
"capability": "image.generate",
"status": "completed",
"attempt": 1,
"error_message": null,
"started_at": "2026-11-19T02:00:01Z",
"completed_at": "2026-11-19T02:00:45Z",
"created_at": "2026-11-19T02:00:00Z",
"artifacts": ["https://…/images/…png?X-Amz-…"]
}artifacts:产物 URL 数组(预签名 7 天)。error_message:不透明固定文案;原始上游错误只留在服务端。- 不属于当前用户的作业返回
404 not_found(不泄漏存在性)。
GET /v1/jobs/:id/events#
作业事件 SSE:
GET /v1/jobs/123/events
Authorization: Bearer nx-...
Accept: text/event-streamdata: {"event":"queued","payload":{},"ts":"2026-11-19T02:00:00Z"}
data: {"event":"started","payload":{},"ts":"2026-11-19T02:00:01Z"}
data: {"event":"completed","payload":{},"ts":"2026-11-19T02:00:45Z"}| 事件 | 说明 |
|---|---|
queued |
入队 |
started |
开始执行(重试会再次出现) |
error |
本次尝试失败,若仍会重试则还有后续 started |
completed |
成功,流结束 |
failed |
终态失败,流结束 |
cancelled |
已取消,流结束 |
要点:
- 每次连接从事件 0 回放,断线重连即可补齐,不需要
Last-Event-ID。 - 服务端每 15 秒发一次 SSE comment 心跳(
: keepalive)。 - 终态事件后服务端关闭连接。
POST /v1/jobs/:id/cancel#
POST /v1/jobs/123/cancel
Authorization: Bearer nx-...{"id": 123, "status": "cancelled"}- 只对未进入终态的作业有效;已完成的作业取消无副作用。
- 取消会全额退还预留余额。
清理与保留#
作业记录与产物 URL 长期保留(产物本身受 S3 生命周期约束)。客户端应在拿到
completed 后及时下载或转存产物。