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 を取得したら速やかに成果物をダウンロードするか別途保存してください。