# ジョブ

> AI アシスタントから Nodaro のジョブを確認、待機、一覧表示、診断します。ジョブエンベロープ、ステータス、保留中のジョブ、再試行できる失敗、代替モデルについても説明します。

Source: https://nodaro.ai/ja/docs/mcp/tools/jobs

**ジョブのツール**を使うと、アシスタントは、Nodaro がアシスタントのために行う処理を追跡できます。ほぼすべての生成ツールはジョブを開始し、すぐにその ID を返します。`get_job` と `wait_for_job` は、ジョブがいつ完了し、結果がどこにあるかを報告します。`list_jobs` は最近のジョブを一覧表示し、`diagnose_run` は失敗の原因を説明します。4 つとも `jobs:read` 権限が必要で、クレジットはかかりません。

## ジョブのステータス
| ステータス | 意味 |
| --- | --- |
| `pending`、`queued`、`processing` | ジョブは待機中か実行中です。確認を続けてください。 |
| `pending_review` | 結果はできていますが、環境の設定により、担当者のレビューが終わるまで保留されています。確認を続け、ジョブを決して再実行しないでください。 |
| `completed` | ジョブは完了しました。`outputUrl` と `outputData` に結果が入っています。 |
| `failed` | ジョブは失敗しました。`retryable` と `guidance` を読んでください。 |
| `cancelled` | ジョブはキャンセルされました。 |

保留中のジョブは、レビュー担当者が承認すると `completed` になり、却下するとポリシー上の理由とともに `failed` になります。MCP の `tasks` API でジョブを追跡するクライアントには、保留中のジョブが `input_required` として表示されます。判断するのはレビュー担当者なので、ユーザーに新しいパラメーターを求めないでください。

## ジョブエンベロープ
`get_job` と `wait_for_job` は、ジョブエンベロープと呼ばれる、同じ構造化された結果を返します。`get_asset` も、`input` を除いた同じ結果を返します。

| フィールド | 内容 |
| --- | --- |
| `jobId`、`jobType` | ジョブ ID と、ジョブの種類 |
| `status`、`progress` | 上記のステータスと、実行中の進行状況 |
| `assetKind` | `image`、`video`、`audio` のいずれか。テキストやデータの結果では null |
| `outputUrl` | 完成した画像、動画、オーディオ |
| `outputData` | 文字起こし、アライメント、分析などの構造化された出力 |
| `input` | 実際にモデルに送られた内容（下記を参照）、または null |
| `errorMessage` | 失敗したジョブのエラー |
| `credits` | ジョブのクレジット |
| `createdAt`、`startedAt`、`completedAt` | タイムスタンプ |
| `retryable`、`guidance`、`suggestedProvider` | 失敗、キャンセル、保留となったジョブで、同じリクエストが成功しうるかどうか、対処方法を説明する 1 文、そして代替モデルがある場合はそのモデル |

`input` は、リクエストのうち安全に公開できる一部で、モデルが受け取った内容を確認するには十分な情報です。次の一覧以外のものは含まれません。

- `prompt`（ピッカー、被写体、リファレンスを組み込んだ後の、最終的なプロンプト）と `userPrompt`（あなた自身が書いた文）。
- `negativePrompt` と、`direction` ピッカーおよび `subject` ピッカーの ID。
- `provider`、`model`、`duration`、`resolution`、`aspectRatio`。
- `imageUrl`、`endFrameUrl` と、リファレンスの画像、動画、オーディオの URL。
- ジョブの `type`。

## `get_job`
自分のジョブを ID で 1 件取得し、ジョブエンベロープとして返します。ジョブが完了するまで、5〜10 秒ごとに確認するときに使います。

**権限**：`jobs:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `job_id` | string | **必須**。生成ツールが返した ID です。 |

**戻り値**：ジョブエンベロープです。

## `wait_for_job`
自分のジョブが完了するまで待機し、完了したらジョブエンベロープを返します。`get_job` を短い間隔で繰り返し呼び出す代わりに使います。

**権限**：`jobs:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `job_id` | string | **必須**。待機するジョブです。 |
| `timeout_s` | integer | 待機する秒数で、1〜120 です。デフォルトは `60` です。 |

**戻り値**：ジョブエンベロープです。期限の時点でジョブがまだ実行中の場合、ステータスは `timeout` になります。これはエラーではありません。`wait_for_job` をもう一度呼び出すか、`get_job` でポーリングします。保留中のジョブでは、すぐに `pending_review` が返されます。時間のかかる動画のレンダリングでは、待機を繰り返すより、`get_job` で 5〜10 秒ごとにポーリングするほうが適しています。

## `list_jobs`
最近のジョブを、ステータス、種類、出力 URL、エラー、クレジット、タイムスタンプを含む構造化データとして一覧表示します。「昨日失敗した生成は何件？」のような質問に使います。ユーザーが結果を見たい場合は、グリッドを表示する [`browse_gallery`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#browse_gallery) を使います。

**権限**：`jobs:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `kinds` | array | 含めるメディアの種類で、`image`、`video`、`audio` を自由に組み合わせます。デフォルトは `["image", "video"]` なので、指定しない限りオーディオは含まれません。 |
| `status` | string | `pending`、`queued`、`processing`、`pending_review`、`completed`、`failed`、`cancelled` のいずれかです。 |
| `scope` | string | 自分のジョブなら `mine`（デフォルト）、ほかのユーザーの最近の公開された結果なら `public` です。 |
| `limit` | integer | 1〜200 です。デフォルトは `50` です。 |
| `cursor` | string | 前のページの `next_cursor` です。 |

**戻り値**：1 ページ分のジョブと、次のページ用の `next_cursor` です。

## `diagnose_run`
ワークフローの実行や単体のジョブが失敗した理由を説明します。どちらの ID でも渡せます。ツールはまずワークフローの実行として調べ、該当しなければジョブとして調べます。

**権限**：`jobs:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。ワークフローの実行 ID またはジョブ ID です。 |

**戻り値**：ワークフローの実行の場合は、すべてのノードと、そのジョブ ID、種類、ステータス（`nodes`）です。実行のノードとジョブ ID の対応がわかるツールは、これだけです。失敗した各ノードには、エラーメッセージ、モデル、実際に課金されたクレジット（`creditsActual`）、失敗の分類、修正方法のヒントも含まれます。

| 失敗の分類 | 意味 |
| --- | --- |
| `content_policy` | 安全フィルターが、プロンプトまたは結果をブロックしました。 |
| `validation` | 設定または入力が受け付けられませんでした。 |
| `rate_limited` | リクエストがレート制限に達しました。 |
| `timeout` | 実行に時間がかかりすぎました。 |
| `post_processing` | モデルは結果を返しましたが、その後の処理が失敗しました。 |
| `provider_error` | モデルのサービスがエラーを返しました。 |
| `unknown` | エラーが、上記のどの分類にも当てはまりません。 |

分類はエラーの文面から推定したものなので、目安として扱ってください。確保されたクレジットは、`post_processing` 以外のすべての分類で自動的に返還されます。`post_processing` の場合は、モデルがすでに処理を終えて結果を渡しているためです。

## ジョブが失敗したとき
1. **`retryable` を確認します**。`false` は、同じリクエストを変更せずに送ると再び失敗することを意味します。これは、コンテンツポリシーでブロックされた場合や、モデルが設定と入力メディアの組み合わせを拒否した場合に起こります。
2. **`suggestedProvider` に従います**。安全フィルターが結果をブロックし、カタログに代替モデルがある場合は、ジョブがそのモデルを示します。別のモデルを推測で選ぶのではなく、同じプロンプトとリファレンスをそのモデルで実行します。
3. **モデルに拒否された場合は、リクエストを変えます**。モデルがこの設定を拒否したというエラーは、長さ、アスペクト比、解像度、またはリファレンスファイルが、そのモデルに合っていないことを意味します。それらを変更するか、[`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) の機能一覧でその組み合わせが許可されているモデルを選びます。
4. **それ以外は再試行します**。モデルのサービスで起きた一時的なエラーは、文面が検証の問題のように見えても、`retryable` のままです。

ほかの対処方法は、[トラブルシューティング](https://nodaro.ai/docs/mcp/troubleshooting)を参照してください。

## Frequently asked questions

### アシスタントは、どのくらいの間隔で Nodaro のジョブを確認すればよいですか？

get_job で 5〜10 秒ごとに確認するか、最大 120 秒待機する wait_for_job を使います。画像は通常 1 分以内に、動画は 2〜10 分で完了します。

### pending_review とはどういう意味ですか？

その環境では結果を公開する前にレビューしており、担当者がこの結果を確認している最中です。失敗ではありません。ジョブの確認を続け、決して再実行しないでください。重複したジョブも保留されるためです。

### ジョブが失敗したら、アシスタントはどうすればよいですか？

ジョブの retryable と guidance を読みます。retryable が false の場合は、設定か入力を変えてから再試行します。suggestedProvider がある場合は、同じプロンプトとリファレンスをそのモデルで実行します。

### ジョブのツールはクレジットを消費しますか？

いいえ。これらのツールは、すでにある処理の状態を読み取るだけです。クレジットを消費するのは、ジョブを開始するツールだけです。