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를 받은 후
산출물을 즉시 다운로드하거나 옮겨 두어야 합니다.