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