NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

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-stream
data: {"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 后及时下载或转存产物。