NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Jobs

GET /v1/jobs/:id · GET /v1/jobs/:id/events · POST /v1/jobs/:id/cancel Status, events, and cancellation for async jobs

Submitting an image generation/editing request returns a job ID. A job can be accessed only by the user who submitted it.


Job states#

queued → running → completed
                 ↘ failed(重试耗尽)
      ↘ cancelled
State Meaning
pending Enqueued (the status returned by the submission response)
running Being executed by a worker
completed Succeeded; artifacts contains the output
failed Terminal failure
cancelled Cancelled by the client

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: array of artifact URLs (presigned, valid for 7 days).
  • error_message: an opaque fixed message; the original upstream error stays server-side only.
  • Jobs that do not belong to the current user return 404 not_found (existence is not leaked).

GET /v1/jobs/:id/events#

Job event 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"}
Event Description
queued Enqueued
started Execution started (appears again on retry)
error This attempt failed; if another retry will follow, another started comes later
completed Succeeded; the stream ends
failed Terminal failure; the stream ends
cancelled Cancelled; the stream ends

Key points:

  • Each connection replays from event 0, so a reconnecting client catches up without Last-Event-ID.
  • The server sends an SSE comment heartbeat (: keepalive) every 15 seconds.
  • The server closes the connection after a terminal event.

POST /v1/jobs/:id/cancel#

POST /v1/jobs/123/cancel
Authorization: Bearer nx-...
{"id": 123, "status": "cancelled"}
  • Effective only for jobs that have not reached a terminal state; cancelling a completed job has no effect.
  • Cancellation fully refunds the reserved balance.

Cleanup and retention#

Job records and artifact URLs are retained indefinitely (the artifacts themselves are subject to S3 lifecycle rules). Clients should download or copy artifacts promptly after receiving completed.