ジョブ

ジョブは、Nodaro での生成の 1 単位です。1 枚の画像、1 本の動画のレンダリング、1 つの音声クリップが、それぞれ 1 つのジョブになります。ノードを実行するとジョブ ID が返り、ワークフローを実行すると AI ノードごとに 1 つのジョブが作成されます。ジョブのエンドポイントは、各ジョブのステータス、進行状況、結果、クレジットを返します。ジョブが completed、failed、cancelled のいずれかになるまでポーリングし、結果を output_data から読み取ります。

エンドポイント

OAuth トークンでジョブを読み取るには、jobs:read スコープが必要です。個人用 API トークンには、スコープは必要ありません。

ジョブの読み取り

curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
    "status": "completed",
    "progress": 100,
    "output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
    "error_message": null,
    "error_hint": null,
    "credit_status": "committed"
  }
}

const { data } = await client.jobs.getStatus(jobId)
if (data.status === 'completed') console.log(data.output_data)

// The full record, with input_data and credits:
const { data: job } = await client.jobs.get(jobId)

nodaro jobs get 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10 --json

GET /v1/jobs/:id/status は、ポーリングのループ向けに作られています。input_data と料金のフィールドを省くため、GET /v1/jobs/:id より軽量です。どちらも { "data": … } を返し、存在しないジョブや自分のものではないジョブには 404 を返します。ジョブのフィールドは、サーバーが送るとおりのスネークケースです。

input_data と output_data は、公開用のビューです。サーバー内部でのみ使うフィールドは、どの呼び出し元に対しても取り除かれます。

ジョブのステータス

修復中のジョブ。モデルが結果を返した後にワーカーが停止した場合、プラットフォームが修復する間、ジョブは recovering: true のまま processing にとどまります。その後、ジョブは自動的に完了するか、クレジットが返還されます。遅いモデルでは数十分かかることがあり、SDK のデフォルトの待機時間より長くなります。runAndWait からの JobTimeoutError はジョブをキャンセルしないので、後でもう一度取得してください。

レビューのために保留されたジョブ。レビューのポリシーを登録したデプロイ環境では、ジョブが pending_review になることがあります。処理は完了しています。保留の間、クレジットはずっと reserved のままで、結果を公開するかどうかは人が判断します。その後、ジョブは completed（承認）、policy-block のヒント付きの failed（却下）、cancelled のいずれかで終わります。保留中のジョブは、処理中のほかのジョブと同じようにキャンセルできます。リクエストを再実行しないでください。重複したジョブも保留されるためです。デプロイ環境がレビューの期限を設定している場合、期限内に誰もレビューしなかったジョブは却下されます。ジョブは failed で終わり、確保されたクレジットは返還され、保留されていた結果は削除されます。保留中のジョブが自動的に承認されることはありません。SDK の runAndWait は、pending_review を検出した最初のポーリングで JobHeldError をスローし、CLI の --watch はコード 3 で終了します。

ポーリングのポイント

• 2〜5 秒ごとにポーリングします。ジョブの状態は、ミリ秒単位ではなく秒単位で変わります。
• ステータスの読み取りは、トークンのレート制限の対象外です。個人用 API トークンの 1 分あたりの制限にカウントされるのは、ワークフローの実行とワークフローの一覧取得だけです。レート制限を参照してください。
• 多くのジョブは、1 回の呼び出しで追跡します。ジョブごとにリクエストを送るのではなく、一括取得のエンドポイントを使います。
• 待機はクライアントに任せます。SDK の client.nodes.runAndWait は、最大 15 分間、2 秒ごとにポーリングします。CLI の --watch は、ジョブが終わるまでポーリングします。

ジョブが失敗した理由

エラーのエラーの表は、ジョブを作成しなかったリクエストを対象としています。後から失敗したジョブには error_message が含まれ、2 種類の失敗では、構造化された error_hint も含まれます。

モデルの安全フィルターがリクエストをブロックした場合：

{ "kind": "safety-block", "class": "safety", "retried": true, "suggestedProvider": "nano-banana-pro" }

• class は copyright、likeness、safety のいずれかです。copyright または likeness によるブロックは確定的で、同じリクエストが通ることはありません。
• 一部のモデルでは、safety フィルターの判定が常に一貫しているとは限りません。GPT Image 2、GPT Image 2.5 Flare、GPT Image 2.5 Sunburst では、Nodaro が同じリクエストを、追加料金なしで 1 回だけ再試行します。retried は、その再試行がすでに行われたかどうかを示します。
• suggestedProvider は、そのモデルに推奨の代替モデルがある場合にだけ含まれます。値は実在するモデル ID なので、同じプロンプトとリファレンスを、そのモデルに送ってください。

デプロイ環境のポリシーがジョブを拒否した場合：

{ "kind": "policy-block", "policyId": "brand-safety", "reason": "This image was not approved for release.", "hookPoint": "result" }

• reason は、デプロイ環境のポリシーがユーザー向けに書いたテキストです。そのまま表示してください。
• hookPoint は、ジョブが実行前に拒否された場合は request、結果が後から拒否された場合は result です。レビュー担当者による却下も、result に含まれます。
• ポリシーによる拒否を、プラットフォームが再試行することはありません。ほかのモデルも提案されません。

それ以外の失敗には error_hint がありません。設定や入力メディアがそのモデルで無効なために、モデルがリクエスト自体を拒否した場合は、error_message にそのことが示されます。設定やメディアを変更してから、もう一度実行してください。モデル側のエラーは、文面にかかわらず、再試行する価値があります。error_hint は、error_message を含むすべてのジョブのペイロードに含まれます。対象は、ジョブ全体、ステータスのルート、一覧、2 つの一括取得のルートです。

ジョブのクレジット

credit_status は、ジョブのクレジットの確保の状態を示します。

credit_status は、GET /v1/jobs/:id、GET /v1/jobs/:id/status、GET /v1/jobs/status に含まれ、GET /v1/jobs と POST /v1/jobs/batch-status には含まれません。安全フィルターやポリシーによるブロックで終わった生成は、必ず返還されます。まれな例外は、ポリシーが結果を拒否する前に、クレジットがすでに精算されていたジョブです。クレジットを参照してください。

自分のジョブの一覧

GET /v1/jobs は、自分のジョブを新しい順に、{ data: Job[], next } の形式で返します。

type と origin は、組み合わせて使えます。ページに含まれる行は limit より少ないことがあり、0 行でも next が付くことがあります。行数を数えるのではなく、next がある限りページの取得を続けてください。

const { data: runs, next } = await client.jobs.list({ type: 'llm-structured', origin: 'my-app' })

複数のジョブの一括ポーリング

次の 2 つのエンドポイントは、1 回のやり取りで最大 100 件のジョブのステータスを返します。

curl -s "https://app.nodaro.ai/v1/jobs/status?ids=$JOB_A,$JOB_B,$JOB_C" \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "jobs": [
    { "id": "0f1a9c2e-…", "status": "completed", "output_data": { "imageUrl": "https://…/a.png" }, "error_message": null, "error_hint": null, "credit_status": "committed" },
    { "id": "7d3e5f60-…", "status": "processing", "output_data": null, "error_message": null, "error_hint": null, "credit_status": "reserved" }
  ]
}

curl -s -X POST https://app.nodaro.ai/v1/jobs/batch-status \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"jobIds\": [\"$JOB_A\", \"$JOB_B\", \"$JOB_C\"]}"

存在しない ID や、ほかのユーザーのジョブの ID は、エラーにならずに除外されます。レスポンスを、自分の ID の一覧と照らし合わせてください。

ジョブのキャンセルと削除

POST /v1/jobs/:id/cancel は、ジョブをキャンセルし、確保していたクレジットを解放します。レスポンスは { "success": true, "cancelled": 1 } です。pending_review で保留中のジョブもキャンセルできます。

DELETE /v1/jobs/:id は、ジョブと、そのジョブが生成した非公開のメディアを削除し、{ "success": true } を返します。ジョブを削除できるのは、その所有者だけです。実行中のジョブはその状態のまま削除されるので、処理を止めたい場合は、先にキャンセルしてください。

curl -s -X POST https://app.nodaro.ai/v1/jobs/$JOB_ID/cancel \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { cancelled } = await client.jobs.cancel(jobId)
await client.jobs.delete(jobId)

nodaro jobs cancel 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10

ワークフローの実行全体を止めるには、代わりにその実行をキャンセルします。実行を参照してください。

コンポーネントの実行

POST /v1/component/execute は、保存したコンポーネント（Component）をバックグラウンドで実行し、{ jobId } とともに 202 を返します。このジョブは、ほかのジョブと同じようにポーリングします。サーバーは、コンポーネントの実行に 90 分を割り当て、さらに、その中にある時間のかかるレンダリングの時間枠を加えます。たとえば、EDL 適用（Apply EDL）ノードの最終レンダリングがそうです。

独自の時間制限を持つクライアントは、サーバーが待機する時間を問い合わせられます。

curl -s https://app.nodaro.ai/v1/component/execute/$JOB_ID/wait-limit \
  -H "Authorization: Bearer $NODARO_API_KEY"

{ "data": { "budgetExcessMs": 0, "waitLimitMs": 5400000, "pendingBudgetedNodes": true } }

• waitLimitMs は、この実行に対するサーバーの待機時間で、90 分に budgetExcessMs を加えた値です。
• budgetExcessMs は、実行が時間のかかるレンダリングを開始するまで 0 のままです。
• pendingBudgetedNodes は、時間のかかるレンダリングがまだ始まっていない間と、実行自体がまだ始まっていない間は true です。そのため、超過分が 0 でも、時間のかかる処理が含まれていないとは限りません。

どちらの値も実行中に変わることがあるので、waitLimitMs に達したら、もう一度問い合わせてください。このルートは実行の所有者にだけ応答し、それ以外のユーザーと、コンポーネントの実行ではないジョブには 404 を返します。エディター自体も、このルールに従っています。時間のかかる処理を含まない実行では 30 分、時間のかかるレンダリングが始まった後は waitLimitMs、pendingBudgetedNodes が true の間は最低 90 分待ち、その後もう一度問い合わせます。

動画生成 Pro の実行

動画生成 Pro は、長い動画を 1 セグメントずつ作り、セグメントの間で進行状況を保存します。そのため、実行を停止して、後から続けられます。動画生成 Pro は Nodaro Cloud で動作し、セルフホスティング環境では、Nodaro Cloud への接続を通じて実行されます。

実行の停止

POST /v1/generate-video-pro/:jobId/stop は、processing の実行を安全に停止します。

• 生成中のセグメントは破棄されますが、モデルはレンダリングを続けるため、その料金は請求されます。
• 残りのセグメントはスキップされます。
• 完成したセグメントはすべてつなぎ合わされ、ジョブの最終的な動画になります。
• 確保されたクレジットのうち、使われなかった分は返還されます。

レスポンスは { "jobId": "…", "stopping": true } です。ジョブのポーリングを続けてください。ジョブは completed で終わり、output_data.pro.stopped が true になり、stoppedAtSegment が含まれます。まだ pending のジョブは、代わりにキャンセルされ、全額が返還されます。

実行の継続

POST /v1/generate-video-pro/continue は、終了したジョブから新しいジョブを開始します。元のジョブのプランと、fromSegment より前の納品済みのセグメントをすべて再利用し、そこから先を生成し直します。

{ "fromJobId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "fromSegment": 4 }

• fromSegment は 1 から数えます。デフォルトは、納品されなかった最初のセグメントです。
• 元のジョブは、終了している必要があります。つまり、停止したジョブ、納品済みのセグメントが 1 つ以上ある失敗したジョブ、完了したジョブのいずれかです。完了した実行で fromSegment を明示的に指定すると、その終盤を生成し直します。
• 支払うのは、生成し直すセグメントの分と、動画生成 Pro の固定料金だけです。
• このルートは Idempotency-Key ヘッダーに対応しているので、再試行したリクエストが 2 つ目のジョブを開始することはありません。

レスポンスは { jobId, continuedFromJobId, fromSegment, segmentCount } です。新しい jobId をポーリングしてください。

curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/$JOB_ID/stop \
  -H "Authorization: Bearer $NODARO_API_KEY"

curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/continue \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c1f0a7e-2b3d-4e5f-8a9b-0c1d2e3f4a5b" \
  -d "{\"fromJobId\": \"$JOB_ID\", \"fromSegment\": 4}"

await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // completes with a partial video

const { jobId: childId } = await client.videoPro.continueRun(jobId, { fromSegment: 4 })

nodaro video-pro stop 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
nodaro video-pro continue 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d --from-segment 4 --watch

どちらのルートも、自分のものではないジョブには 404 を、動画生成 Pro の実行ではないジョブには 400 を返します。

実行の見積もり

POST /v1/credits/video-pro-estimate は、ジョブを作成したりクレジットを確保したりせずに、動画生成 Pro の実行の料金を見積もります。

{ "provider": "gemini-omni-flash", "resolution": "720p", "duration": 12, "renderMethod": "keyframes", "segmentMode": "short" }

ある設定例では、レスポンスは { "data": { "credits": 760, "upperBound": true } } になります。現在の料金は、実際のレスポンスで確認してください。

• segmentMode が short または long の場合、実行はまず、アクション全体をソースの区間に割り当てます。upperBound: true は、その金額がプラン作成前の確保の上限であることを意味します。最終的な請求額は、実際のプランに従います。
• planOnly の見積もりはプラン作成の料金を対象とし、upperBound: false を返します。その sourceSegmentDurations と planCheckpoint は、同じモードと設定のまま、sourceSegmentDurations と seedPlan として送り返せます。

セグメント分割の仕組みと各設定の役割については、動画生成 Pro を参照してください。