ジョブ
AI アシスタントから Nodaro のジョブを確認、待機、一覧表示、評価、診断します。ジョブエンベロープ、ステータス、保留中のジョブ、再試行できる失敗、代替モデルについても説明します。
ジョブのツールを使うと、アシスタントは、Nodaro がアシスタントのために行う処理を追跡できます。ほぼすべての生成ツールはジョブを開始し、すぐにその ID を返します。get_job と wait_for_job は、ジョブがいつ完了し、結果がどこにあるかを報告します。list_jobs は最近のジョブを一覧表示して絞り込み、rate_job は結果を評価し、diagnose_run は失敗の原因を説明します。どのツールもクレジットはかかりません。
ジョブのステータス
| ステータス | 意味 |
|---|---|
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 と 2 つのクレジットの数値を除いた同じ結果を返します。
| フィールド | 内容 |
|---|---|
jobId、jobType | ジョブ ID と、ジョブの種類 |
status、progress | 上記のステータスと、実行中の進行状況 |
assetKind | image、video、audio のいずれか。テキストやデータの結果では null |
outputUrl | 完成した画像、動画、オーディオ |
width、height | ジョブが記録した場合の、出力のピクセル単位のサイズ。下記を参照してください |
outputData | 文字起こし、アライメント、分析などの構造化された出力 |
input | 実際にモデルに送られた内容(下記を参照)、または null |
errorMessage | 失敗したジョブのエラー |
errorDetail | 失敗についてのモデルのサービス自体の説明で、リンクはホスト名まで切り詰められ、秘密情報は取り除かれます。説明がない場合は null です。ユーザーに表示しますが、この値で処理を分岐させないでください。失敗の説明が誰に届くかを参照してください |
credits | ジョブ自身が受け付けられたときに確保したクレジット。この額は変わりません |
creditsCharged | 確保した額が精算された後にジョブにかかった費用で、ジョブが実行したステップも含みます(テキストのペイロードの data では credits_charged)。下記を参照してください |
creditsHeld、creditsReleased | ステップの確保を含む実行全体の確保額と、実行の中のすべての確保が精算された後に戻った額(credits_held と credits_released)。下記を参照してください |
createdAt、startedAt、completedAt | タイムスタンプ |
retryable、guidance、suggestedProvider | 失敗、キャンセル、保留となったジョブで、同じリクエストが成功しうるかどうか、対処方法を説明する 1 文、そして代替モデルがある場合はそのモデル |
preview | プレビューの品質で作った EDL 適用のレンダーで true です。このとき outputData.quality は "proxy" で、最終版ではなく、確認用の非公開の 720p のカットです |
creditsCharged は credits より少ないことがあります。この値にはジョブが実行したステップが含まれます。ほかのジョブを代わりに実行するジョブ(たとえば、Video Remake の実行のリファレンスの準備、マスク、動画)は、各ステップが精算された時点でそのステップの分も課金されます。ジョブ自身の確保が返還された場合は、0 に精算済みのステップの額を足したものです。たとえば、リファレンスとマスクのステップが課金された後に返還された Video Remake の実行は、credit_status: "refunded" で creditsCharged: 165 となります。ジョブ自身の確保がまだ開いているあいだ、実行の中で何も確保されなかった場合、ステップを一時的に読み取れない場合は null です。この null は不明という意味で、低い額になることはありません。
creditsHeld は、ステップの確保を含む実行全体の確保額です。creditsReleased は、実行の中のすべての確保が精算された後に戻った額で、それまでは null です。たとえば、888 クレジットを確保して 444 クレジットで精算されたジョブは、credits: 888、creditsCharged: 444、creditsHeld: 888、creditsReleased: 444 となります。
width と height は、Nodaro がサイズの記録を始めた後に完了した画像のジョブと、画像オーバーレイ、動画オーバーレイ、動画マスク、マスク合成のジョブに含まれます。画像では、保存された outputUrl のサイズで、EXIF の回転を適用した値です。次のステップのアスペクト比を選ぶときに読み取ってください。複数の画像を作ったジョブには outputData.images もあり、画像ごとに { url, width, height } が含まれます。
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 | 待機する秒数で、最大 45 です。デフォルトは 45 です。120 までの値も受け付けられますが、待機は 45 秒です。 |
戻り値:ジョブエンベロープです。MCP クライアントはツールの呼び出しを独自の時間で打ち切り、それは 60 秒であることが多いため、各呼び出しは 45 秒以内に答えます。その時点でジョブがまだ実行中の場合、ステータスは timeout になり、ジョブの progress、jobType、createdAt、startedAt が含まれます。これはエラーではありません。同じ job_id で wait_for_job をもう一度呼び出してください。待機は止まったところから続き、ジョブには影響しないため、生成を再実行しないでください。動画は 2〜10 分かかることがあるため、何回か呼び出すことになるか、get_job で 5〜10 秒ごとにポーリングします。保留中のジョブでは、すぐに pending_review が返されます。
list_jobs
最近のジョブを、ステータス、種類、出力 URL、エラー、クレジット、タイムスタンプを含む構造化データとして一覧表示します。「昨日失敗した生成は何件?」のような質問に使います。ユーザーが結果を見たい場合は、グリッドを表示する browse_gallery を使います。
権限:jobs:read。クレジット:無料。
| パラメーター | 型 | 説明 |
|---|---|---|
kinds | array | 含めるメディアの種類で、image、video、audio を自由に組み合わせます。デフォルトは ["image", "video"] なので、指定しない限りオーディオは含まれません。 |
status | string または array | 自分のジョブのみです。1 つのステータスか、ステータスのリストです。pending、queued、processing、pending_review、completed、failed、cancelled です。 |
types | array | 自分のジョブのみです。1〜20 個のジョブの種類で、ジョブを作ったルートです。たとえば generate-image や llm-structured です。 |
sources | array | 自分のジョブのみです。ジョブを作成した経路で、1 つ以上指定します。mcp(Claude や ChatGPT などの MCP クライアント)、web、cli、sdk、extension、app、api、internal のいずれかです。 |
favorited | boolean | 自分のジョブのみです。true はお気に入りにしたジョブを、false はそれ以外を残します。 |
rating | string | 自分のジョブのみです。good、bad、rated(何らかの評価あり)、unrated のいずれかです。 |
project_id | string | 自分のジョブのみです。このプロジェクトのセッションが現在保持しているジョブで、各ジョブは 1 回だけ表示されます。none を指定すると、プロジェクトのないセッションが保持しているジョブになります。 |
in_session | boolean | 自分のジョブのみです。false を指定すると、どのセッションにも保持されていないジョブになります。アプリでは一般として表示されます。true を指定すると、1 つ以上のセッションが保持しているジョブになります。 |
with_sessions | boolean | 自分のジョブのみです。各ジョブに、それを保持しているセッション(ID、タイトル、プロジェクト ID)の一覧も加わります。 |
scope | string | 自分のジョブなら mine(デフォルト)、ほかのユーザーの最近の公開された結果なら public です。 |
limit | integer | 1〜200 です。デフォルトは 50 です。 |
cursor | string | 前のページの next_cursor です。 |
戻り値:1 ページ分のジョブと、次のページ用の next_cursor です。
public スコープには、公開ギャラリーに表示されるものが、browse_gallery と同じモデレーションで一覧表示され、ほかのクリエイターの ID は含まれません。どちらのスコープでも、1 ページのジョブが limit より少なく、それでも next_cursor が含まれることがあります。null になるまでたどり続けてください。
公開作品を許可しないデプロイ(outputs.allowPublic: false)では、public スコープは何も一覧表示せず、{ "data": [], "next_cursor": null } を返します。
自分のジョブでは、フィルターは GET /v1/jobs と同じように働き、AND で組み合わされます。types を指定するとデフォルトの kinds が解除されるので、llm-structured の下書きのようなメディアのないジョブも一覧に含まれます。メディアだけに絞るには、kinds も指定してください。types、sources、favorited、rating、project_id、in_session、with_sessions は、scope: "public" と一緒に指定すると拒否されます。削除したジョブが一覧に含まれることはありません。そのジョブは list_trash にあります。
自分の各ジョブには、favorited(true または false)と rating("good"、"bad"、null のいずれか)が含まれます。一時的に読み取れない場合はどちらも省略され、これは false ではなく不明を意味します。public スコープの行には、どちらも含まれません。
自分の各ジョブには、ジョブ自身が受け付けられたときに確保した変わらない額である credits と、確保した額が精算された後にかかった費用である credits_charged が含まれます。credits_charged には、ジョブが実行したステップが含まれます。ジョブは確保した額より少なく精算されることがあり、残りは残高に戻ります。実行自身の確保が返還された場合、credits_charged は 0 に精算済みのステップの額を足したものです。ジョブ自身の確保がまだ開いているあいだ、実行の中で何も確保されなかった場合、ステップを一時的に読み取れない場合は null です。credits_held はステップの確保を含む実行全体の確保額、credits_released は実行の中のすべての確保が精算された後に戻った額です(それまでは null)。ジョブにかかった費用を合計するには、credits ではなく credits_charged を足し合わせてください。public スコープの行には、この 3 つはどれも含まれません。
自分のジョブには EDL 適用のレンダーも含まれ、出力の種類(カットは video、ミックスは audio)に分類されます。プレビューには preview: true が付きます。public スコープには、EDL 適用のレンダーは表示されません。
rate_job
自分のジョブを good か bad で評価するか、評価をクリアします。1 つのジョブに付く評価は 1 つで、評価できるのはジョブの所有者だけです。ほかの人のジョブや、ジョブではない ID には「見つかりません」と返されます。
権限:assets:write。クレジット:無料。
| パラメーター | 型 | 説明 |
|---|---|---|
job_id | string | 必須。自分のジョブの 1 つです。 |
rating | string または null | 必須。good か bad、または評価をクリアする null です。 |
戻り値:{ data: { jobId, rating } } です。評価は、評価で絞り込める list_jobs と、GET /v1/jobs に表示されます。
diagnose_run
ワークフローの実行や単体のジョブが失敗した理由を説明します。どちらの ID でも渡せます。ツールはまずワークフローの実行として調べ、該当しなければジョブとして調べます。
権限:jobs:read。クレジット:無料。
| パラメーター | 型 | 説明 |
|---|---|---|
id | string | 必須。ワークフローの実行 ID またはジョブ ID です。 |
戻り値:ワークフローの実行の場合は、すべてのノードと、そのジョブ ID、種類、ステータス(nodes)です。実行のノードとジョブ ID の対応がわかるツールは、これだけです。失敗した各ノードには、エラーメッセージ、モデル、実際に課金されたクレジット(creditsActual)、失敗の分類、修正方法のヒントも含まれます。モデルのサービス自体の説明も、説明があり、あなたが読める場合は providerReason として含まれます。run_workflow で続けられる失敗した実行には、resumeHint も含まれます。これは、その実行を止まった所から続ける run_workflow の呼び出しです。失敗したアプリの実行には、get_app_run と同じく、代わりに retry_app_run の呼び出しが含まれます。
失敗の説明が誰に届くか
失敗についてのモデルのサービスの説明は、ジョブの所有者のものです。次の場合、errorDetail と providerReason は省略されるか、null になります:
- ほかのユーザーの公開ジョブに対する
get_assetと、scope: "public"を指定したlist_jobs。どちらも、そのユーザーの ID も返しません。 - 開けないワークフローの実行のジョブ(実行した他人の共有リンクや公開アプリなど)。これは
get_job、wait_for_job、list_jobs、get_asset、diagnose_runで同じです。 - この説明を管理者だけに限定しているデプロイメント。MCP のセッションは、管理者のものとしては扱われません。
| 失敗の分類 | 意味 |
|---|---|
content_policy | 安全フィルターが、プロンプトまたは結果をブロックしました。 |
validation | 設定または入力が受け付けられませんでした。 |
rate_limited | リクエストがレート制限に達しました。 |
timeout | 実行に時間がかかりすぎました。 |
post_processing | モデルは結果を返しましたが、その後の処理が失敗しました。 |
provider_error | モデルのサービスがエラーを返しました。 |
unknown | エラーが、上記のどの分類にも当てはまりません。 |
分類はエラーの文面から推定したものなので、目安として扱ってください。確保されたクレジットは、post_processing 以外のすべての分類で自動的に返還されます。post_processing の場合は、モデルがすでに処理を終えて結果を渡しているためです。
完了した実行は、get_app_run と同じように、outcome("succeeded" または "nothing_new")も報告します。入力に何も届かなかったために実行がスキップしたノードには、skipReason: "empty_input" が付きます。新しいものが見つからなかった実行には、説明すべき失敗はありません。何も問題は起きておらず、処理する対象がなかっただけです。
ジョブが失敗したとき
retryableを確認します。falseは、同じリクエストを変更せずに送ると再び失敗することを意味します。これは、コンテンツポリシーでブロックされた場合や、モデルが設定と入力メディアの組み合わせを拒否した場合に起こります。モデルが理由を示さなかった拒否はretryable: trueです。suggestedProviderに従います。安全フィルターが結果をブロックし、カタログに代替モデルがある場合は、ジョブがそのモデルを示します。別のモデルを推測で選ぶのではなく、同じプロンプトとリファレンスをそのモデルで実行します。- モデルに拒否された場合は、リクエストを変えます。モデルがこの設定を拒否したというエラーは、長さ、アスペクト比、解像度、またはリファレンスファイルが、そのモデルに合っていないことを意味します。それらを変更するか、
list_modelsの機能一覧でその組み合わせが許可されているモデルを選びます。モデルが理由を示さなかったというエラーは、一時的なものか、サイズや形式など入力メディアが原因のことがあります。一度だけ再実行し、再び失敗したら入力メディアを変更します。 - それ以外は再試行します。モデルのサービスで起きた一時的なエラーは、文面が検証の問題のように見えても、
retryableのままです。
ほかの対処方法は、トラブルシューティングを参照してください。
よくある質問
アシスタントは、どのくらいの間隔で Nodaro のジョブを確認すればよいですか?
get_job で 5〜10 秒ごとに確認するか、1 回の呼び出しにつき最大 45 秒待機する wait_for_job を使います。画像は通常 1 分以内に、動画は 2〜10 分で完了します。
pending_review とはどういう意味ですか?
その環境では結果を公開する前にレビューしており、担当者がこの結果を確認している最中です。失敗ではありません。ジョブの確認を続け、決して再実行しないでください。重複したジョブも保留されるためです。
ジョブが失敗したら、アシスタントはどうすればよいですか?
ジョブの retryable と guidance を読みます。retryable が false の場合は、設定か入力を変えてから再試行します。suggestedProvider がある場合は、同じプロンプトとリファレンスをそのモデルで実行します。
ジョブのツールはクレジットを消費しますか?
いいえ。これらのツールは、すでにある処理の状態を読み取るだけです。クレジットを消費するのは、ジョブを開始するツールだけです。
関連ページ
MCP ツールリファレンス
ギャラリーとアセット
トラブルシューティング
ワークフローの実行
最終更新