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