Jobs
GET /v1/jobs/:id·GET /v1/jobs/:id/events·POST /v1/jobs/:id/cancelStatus, 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-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"}| 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.