NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

ジョブ

Nodaro のジョブをポーリングしてステータスと結果を取得します。ジョブの一覧の絞り込み、結果の評価とお気に入り、画像サイズの読み取り、100 件の一括確認、キャンセルも扱います。

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

エンドポイント

メソッドパス説明
GET/v1/jobs/:id/statusポーリング用の軽量なステータスです。ステータス、進行状況、結果、エラーを返します。
GET/v1/jobs/:id送信した内容(input_data)とクレジットを含む、ジョブ全体を返します。
GET/v1/jobs自分のジョブを、新しい順にページ単位で返します。
GET/v1/jobs/status?ids=…最大 100 件のジョブのステータスを返します。ID はクエリで指定します。
POST/v1/jobs/batch-status最大 100 件のジョブのステータスを返します。ID はリクエストボディで指定します。
PUT/v1/jobs/:id/rating自分のジョブを good または bad で評価するか、評価をクリアします。
PATCH/v1/jobs/:id自分のジョブに名前を付けるか、名前を消します。
POST/v1/jobs/from-upload自分のアプリで編集した画像を、ジョブとして記録します。
POST/v1/gallery/favoriteジョブをお気に入りに追加するか、お気に入りから外します。
GET/v1/gallery/favoritesお気に入りに追加したジョブの ID です。
POST/v1/jobs/:id/cancelジョブをキャンセルし、確保されたクレジットを解放します。
DELETE/v1/jobs/:idジョブをゴミ箱に移します。?forever=true を付けると、すでにゴミ箱にあるジョブを完全に削除します。
POST/v1/jobs/:id/restore削除したジョブをゴミ箱から戻します。
GET/v1/trash自分のゴミ箱です。セッションから外したアイテムと、削除したジョブが入っています。
GET/v1/component/execute/:jobId/wait-limitコンポーネントの実行を、サーバーがどれだけ待つかを返します。
POST/v1/generate-video-pro/:jobId/stop動画生成 Proの実行を停止し、完成したセグメントを残します。
POST/v1/generate-video-pro/continue動画生成 Pro の実行を、新しいジョブとして続けます。
POST/v1/credits/video-pro-estimate動画生成 Pro の実行を開始せずに、料金を見積もります。

OAuth トークンでジョブを読み取るには、jobs:read スコープが必要です。個人用 API トークンには、スコープは必要ありません。ポーリングする代わりに、ジョブが終わったときに Nodaro からサーバーに通知させるには、Webhook エンドポイントを登録します。

ジョブの読み取り

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 を返します。ジョブのフィールドは、サーバーが送るとおりのスネークケースです。

フィールド意味
idジョブ ID です。
statusジョブの状態です。ジョブのステータスを参照してください。
progress0〜100 です。
output_data結果です。メディアのジョブには imageUrl、videoUrl、audioUrl のいずれかが入り、多くの場合は thumbnailUrl も付きます。その他のジョブには、text や json など、独自のフィールドが入ります。
error_messageジョブが失敗した理由を、文章で示します。
error_hint5 種類の失敗について、構造化された理由を示します。ジョブが失敗した理由を参照してください。
error_detailジョブが失敗したときにプロバイダー自身が述べた内容、または null です。プロバイダー自身の言葉を参照してください。
credit_statusreserved、committed、refunded、null のいずれかです。ジョブのクレジットを参照してください。
recoveringモデルが結果を返した後にワーカーが停止したジョブを、プラットフォームが修復している間は true です。
input_dataジョブ全体を取得した場合のみ。修正後の、実際に送られた内容です。たとえば、最終的な prompt、自分で書いた userPrompt、direction の ID などです。
creditsジョブ全体を取得した場合と一覧。ジョブが受け付けられたときに確保したクレジットです。この額は変わりません。
credits_chargedジョブ全体を取得した場合と一覧。確保した額が精算された後にジョブにかかった費用で、ジョブが実行したステップも含みます。または null です。ジョブのクレジットを参照してください。
credits_held、credits_releasedジョブ全体を取得した場合と一覧。ステップの確保を含む実行全体の確保額と、すべての確保が精算された後に戻った額です。ジョブのクレジットを参照してください。
job_type、source、source_detailジョブ全体を取得した場合のみ。ジョブの種類と、ジョブの出どころです。source は internal、mcp、app、cli、sdk、extension、web、api のいずれかで、source_detail は sdk/1.10.0 のようにクライアントを示します。
session_idジョブ全体と一覧。ジョブが整理された生成セッションです。なければ null です。
favorited、ratingジョブ全体と一覧。自分のお気に入り(true または false)と自分の評価("good"、"bad"、null のいずれか)です。お気に入りと評価を参照してください。
titleジョブ全体と一覧。自分で付けたジョブの名前です。名前を付けるまでは null です。お気に入りと評価を参照してください。
created_at、started_atジョブ全体を取得した場合のみ。タイムスタンプです。
completed_atジョブが完了した日時(サーバーの時計による)です。完了するまでは null です。ステータスのルートもこれを返します。

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

EDL 適用のジョブの output_data は、レンダリングが何から作られたかを示します。quality はプレビューなら "proxy"、最終版なら "final" で、clipKey は、リクエストで指定した場合にプランのクリップを示します。planBasis はリクエストで指定した場合に返され、renderBasis はサーバーが書き込む、レンダリング自身の設定とソースのスタンプです。話者ビューのジョブも、同じ 3 つのスタンプを送られたとおりに返します。古い EDL 適用のジョブは、注文されたときの品質で読み取られます。

完了した Grok Imagine の動画ジョブ(grok または grok-i2v)で、リクエストが解像度を指定していた場合は、その解像度がリクエストに記録されたとおり output_data.recordedResolution に入ります。その動画の Grok Extend は、この解像度で料金が決まります。

画像のジョブの画像サイズ

output_data に imageUrl があるジョブには、すべて画像のサイズ(ピクセル)も含まれます。生成、編集、画像から画像への実行、コラージュ、オーバーレイ、抽出したフレームなどです。クライアントは、画像が読み込まれる前にグリッドをレイアウトしたり、サイズを表示したり、サイズで並べ替えたりできます。

フィールド型意味
width、heightintegerimageUrl の、保存されているファイルとしてのサイズ(ピクセル)です。ダウンロードするものと同じで、無料ティアのウォーターマークも含みます。EXIF の向きが適用されるので、ブラウザーが表示するサイズです。
images{ url, width, height }[]複数の画像を作ったジョブで、imageUrls の横にあります。画像ごとに 1 件で、imageUrls と同じ順序です。サイズを読み取れなかった項目には、url だけがあります。imageUrls 自体は、文字列の配列のままです。
{
  "imageUrl": "https://cdn.nodaro.ai/images/<jobId>.png",
  "imageUrls": ["https://cdn.nodaro.ai/images/<jobId>.png", "https://cdn.nodaro.ai/images/<jobId>-v1.png"],
  "width": 1024,
  "height": 1536,
  "images": [
    { "url": "https://cdn.nodaro.ai/images/<jobId>.png", "width": 1024, "height": 1536 },
    { "url": "https://cdn.nodaro.ai/images/<jobId>-v1.png", "width": 1024, "height": 1536 }
  ]
}

3 つのフィールドはすべて省略される可能性があるものとして扱ってください。サイズが記録されるようになる前に完了したジョブには、どれも含まれません。また、サーバーが読み取れなかったサイズは、推測されずに省かれます。これらのフィールドは、GET /v1/jobs、GET /v1/jobs/:id、GET /v1/jobs/:id/status のすべてのジョブの読み取りに含まれます。MCP のジョブ用ツール get_job、wait_for_job、get_asset は、outputUrl の横に width と height を含みます。

ジョブのステータス

ステータス最終状態意味
pending、queued、processingいいえジョブは実行を待っているか、実行中です。
pending_reviewいいえ結果はできており、デプロイ環境が人によるレビューのために保留しています。ポーリングを続けてください。
completedはい結果は output_data にあります。
failedはい理由は error_message と error_hint に示されます。
cancelledはいあなたまたはプラットフォームが、ジョブをキャンセルしました。

修復中のジョブ。モデルが結果を返した後にワーカーが停止した場合、プラットフォームが修復する間、ジョブは 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 が含まれ、5 種類の失敗では、構造化された 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 なので、同じプロンプトとリファレンスを、そのモデルに送ってください。
  • subject: "input_video" は、プロバイダーが、プロンプト、リファレンス画像、結果ではなく、ジョブの入力動画そのものを拒否した場合に含まれます。別のクリップを送ってください。
  • subject: "input_image" は常に class: "copyright" と一緒に、プロバイダーがジョブの入力画像のいずれかを、著作権で保護されている可能性があるとして拒否した場合に含まれます。別の画像を送ってください。プロンプトを言い換えても解決しません。
  • subject: "prompt" は、プロバイダー自身の文面がプロンプトを挙げた場合に、どの class でも含まれます。プロンプトを変えれば解決します。
  • subject: "audio" は、プロバイダー自身の文面が、画像ではなく生成されたオーディオを原因とした場合に、どの class でも含まれます。
  • 知らない subject は、ないものとして扱ってください。

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

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

自分のクレジットを確保するステップが拒否されたために、ジョブが途中でクレジット不足になった場合(たとえば、Video Remake やトレンドの実行が開始する動画):

{ "kind": "credits", "code": "insufficient_credits" }
  • code は、その拒否自体のコードで、小文字のスネークケースです。残高でステップをまかなえなかった場合は insufficient_credits、プランやワークスペースの上限の場合は free_video_limit、instance_cap_reached、budget_exceeded、member_cap_exceeded、user_allowance_exceeded などです。不明なコードは insufficient_credits と同じように扱ってください。
  • ジョブのクレジットは返還されます。クレジットの追加か上限の引き上げをユーザーに依頼してから、もう一度実行してください。それまでは、同じリクエストは同じように失敗します。

プロバイダーがジョブの入力動画を拒否した場合で、コンテンツポリシーの分類が示されないもの。メッセージは、ポリシーではなくファイルについてのものです。

{ "kind": "input-refused", "subject": "input_video" }

ほかの失敗と同じように扱ってください。ほかのモデルは提案されませんが、どの入力を変えればよいかはわかります。別のクリップを送ってください。

プロバイダーが、送られたままのリクエストを拒否した場合で、設定、ファイルの形式やサイズ、プロンプトの長さなど、リクエストの不備が示されるもの。

{ "kind": "request-refused", "subject": "input_video" }

subject: "input_video" が含まれるのは、プロバイダーの文面が、長さやサイズ、キャラクターが見つからないなど、入力動画を不備として挙げた場合だけです。その場合は、別のクリップにすれば結果が変わる可能性があります。同じリクエストは同じように拒否されるので、そのまま再実行しないでください。入力画像、動画、プロンプト、または設定を変えてください。コンテンツポリシーによるブロックではありません。Video Remake やトレンドの実行のように、複数のステップでできたジョブでは、1 つのステップの拒否です。

それ以外の失敗には error_hint がありません。設定や入力メディアがそのモデルで無効なために、モデルがリクエスト自体を拒否した場合は、error_message にそのことが示されます。設定やメディアを変更してから、もう一度実行してください。モデルが理由を示さず、一般的な「Generation failed. Please try again later.」(生成に失敗しました。後でもう一度お試しください)というメッセージだけでリクエストを拒否することがあります。その場合、error_message には、モデルが理由を示さなかったこと、原因が一時的なものか、サイズや形式など入力メディアにある可能性があることが示されます。そのジョブを一度だけ再実行し、再び失敗したら入力メディアを変更してください。モデル側のエラーは、文面にかかわらず、再試行する価値があります。error_hint は、error_message を含むすべてのジョブのペイロードに含まれます。対象は、ジョブ全体、ステータスのルート、一覧、2 つの一括取得のルートです。

プロバイダー自身の言葉

失敗したジョブには、失敗についてのプラットフォーム自身の文である error_message に加えて、error_detail が含まれます。これは、ジョブが失敗したときに保存された、プロバイダー自身が述べた内容です。その中のリンクはホストまでに切り詰められ、シークレットは取り除かれます。それ以外はプロバイダー自身の言葉のままです。たとえば task failed: [400] Request blocked: The uploaded image may contain protected or restricted IP content. です。

  • プロバイダーが何も述べなかった場合は null です。たとえば、何かが送られる前の拒否、タイムアウト、時間切れになったキューの待ちです。古いサーバーでは、このフィールドは省略されます。
  • error_message の横に表示してください。分岐には error_hint を使い、この言葉は使わないでください。
  • 含まれる場所:error_message と同じジョブのペイロードと、job.failed の Webhook イベントの中のジョブです。ワークフローの実行で失敗したノードは、nodeStates の errorDetail としてこれを持ちます。実行を参照してください。

この言葉はプロンプトを引用することがあるため、読むことを許された呼び出し元にだけ届きます:

  • トレンドの実行は、その言葉をテキストと一緒に伏せます。隠れた入力を引用することがあるためです。
  • ワークフローの実行のジョブがこの言葉を持つのは、その所有者が、実行したワークフローを開ける場合だけです。つまり、ワークフローの作成者か共有相手です。他人の共有リンクから開始した実行のジョブはあなたのものですが、すべてのジョブのペイロードと job.failed イベントで error_detail: null になります。
  • 公開アプリの実行者は、この言葉を受け取りません。
  • ユースケースノードの非表示の実行(エピソードを引き締めるなど)は、保存したワークフローを実行しません。ワークフローの実行のノードがそれを開始した場合は、その実行にリンクされ、その実行のワークフローで判断されます。ノードの状態とジョブのどちらも同じです。別の非表示の実行の中にある非表示の実行は、リンクをたどって最も近いワークフローの実行で判断されます。単独で開始した非表示の実行は、その所有者のものです。
  • どの実行にも属さない自分のジョブ(単独で実行した 1 つのノードなど)は、その言葉をあなたに届けます。開始した実行にリンクされていないジョブも同じです。それは、一部のノードタイプのジョブ、このリンクが記録される前に作られたユースケースノードの非表示の実行のジョブ、ワークフローが削除された実行のジョブです。実行がなくなった、リンクされた非表示の実行は、管理者以外の誰にもその言葉を見せません。
  • デプロイメントは、この言葉を管理者だけに限定できます。サーフェスプロファイルで jobs.errorDetail: "admin" を指定すると、管理者でない呼び出し元はすべて error_detail: null を受け取ります。これはプロバイダーの言葉がない失敗と同じ見え方なので、クライアントを変更する必要はありません。エディションとサーフェスプロファイルを参照してください。

ジョブのクレジット

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

値意味
reservedジョブの実行中、クレジットが確保されています。
committedジョブが結果を返し、クレジットが課金されました。
refunded確保されていたクレジットが解放されました。たとえば、安全フィルターでブロックされた後です。
nullジョブに、報告するクレジットの記録がありません。

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

ジョブの credits は、ジョブ自身が受け付けられたときに確保した額で、変わることはありません。GET /v1/jobs と GET /v1/jobs/:id には credits_charged も含まれます。これは、確保した額が精算された後にジョブにかかった費用で、同じクレジットの記録から読み取ります。

  • credits_charged は credits より少ないことがあります。一部のジョブは、使う額より多くを確保します。たとえば、再レンダリングの可能性や、実行後に測る長さに備えるためです。残りは残高に戻ります。
  • ジョブ自身の確保が返還された場合、credits_charged は 0 に、精算済みのステップの額を足したものです。たとえば、リファレンスとマスクのステップが課金された後に返還された Video Remake の実行は、credit_status: "refunded" で credits_charged: 165 となります。
  • ジョブ自身の確保がまだ開いているあいだ(credit_status: "reserved")は、一部のステップがすでに精算されていても、credits_charged は null です。実行の中で何も確保されなかった場合も null です。

ジョブにかかった費用を合計するには、credits ではなく credits_charged を足し合わせてください。たとえば、888 クレジットを確保して 444 クレジットで精算されたジョブは、credits: 888、credits_charged: 444、credit_status: "committed" となります。

ほかのジョブを実行するジョブ

credits_charged は、ステップを含めた実行全体としてのジョブの課金額です。一部のジョブは、ほかのジョブを代わりに実行します。たとえば、Video Remake の実行は、リファレンスの準備、マスクの作成、動画のレンダリングを、それぞれ独立したステップとして行います。ステップが単独で一覧に出ることはなく、精算された時点で課金されます。

  • 確保がまだ開いているステップは、まだ何も加えません。返還されたステップは 0 を加えます。
  • credits_held は実行全体の確保額で、ジョブ自身の credits にステップの確保額を足したものです。ステップのないジョブでは credits と同じです。
  • credits_released は、実行の中のすべての確保が精算された後に、確保額から戻った額(credits_held − credits_charged)です。それまでは null です。
  • credits と credit_status は、ジョブ自身のものです。
  • ステップを一時的に読み取れない場合、credits_charged、credits_held、credits_released は null になります。これは不明という意味で、低い額になることはありません。

たとえば、自身の確保が 44 で、66 のリファレンスのステップが 2 つ、33 のマスク、3,564 を確保して 854 で精算された動画を持つ Video Remake のプレビューは、credits: 44、credits_charged: 1063、credits_held: 3773、credits_released: 2710 となります。

ワークフローの実行も、ノードを同じように数えます。ノードのクレジットには、失敗したノードも含めて、そのジョブの精算済みのステップが入り、実行の totalCreditsUsed も同様です。ノードが終わった後に精算されたステップは、実行の終了時に数えられます。

自分のジョブの一覧

GET /v1/jobs は、自分のジョブを新しい順に、{ data: Job[], next } の形式で返します。子ジョブ、つまりほかのジョブが自分の作業の一ステップとして開始したジョブは、一覧に含まれません。名前が __ で始まる出力キーはサーバー専用で、どのジョブの読み取りでも返されません。

クエリパラメーター意味
limitページのサイズで、最大 100 です。
cursor前のページの next の値です。
status1 つ以上のジョブのステータスです。pending、queued、processing、pending_review、completed、failed、cancelled を指定できます。不明なステータスには 400 validation_error が返されます。
typeジョブを作成した 1 つ以上のルートで、最大 20 個です。たとえば llm-structured や video-analysis です。
originジョブを送ったクライアントアプリで、完全一致で指定します。たとえば studio です。
sourceジョブを作成した経路で、1 つ以上指定します。mcp、cli、sdk、web、extension、app、api、internal のいずれかで、ジョブの source フィールドの値です。source=mcp は、Claude や ChatGPT などの MCP クライアントが作成したものを一覧にします。
favoritedtrue はお気に入りに追加したジョブを、false は追加していないジョブを残します。
ratinggood、bad、rated(何らかの評価あり)、unrated のいずれかです。
projectIdこのプロジェクトのセッションが現在保持しているジョブです。各ジョブは 1 回だけ表示されます。none を指定すると、プロジェクトのないセッションが保持しているジョブになります。inSession=false とは組み合わせられません。
inSessionfalse を指定すると、現在どのセッションにも保持されていないジョブになります。アプリでは一般として表示されます。true を指定すると、1 つ以上のセッションが保持しているジョブになります。
withSessionstrue を指定すると、各ジョブに sessions: [{ id, title, projectId }](そのジョブが入っているセッション)が加わります。
batchId1 回の画像生成のバッチのジョブです。1 回の呼び出しで複数の画像を参照してください。
attachToCharacterId1 人のキャラクターのジョブです。キャラクターを参照してください。

status、type、source には、カンマ区切りのリスト(status=failed,cancelled)か、繰り返したパラメーター(type=a&type=b)を指定します。どのフィルターも完全一致で、フィルターは組み合わせて使えます。ページに含まれる行は limit より少ないことがあり、0 行でも next が付くことがあります。行数を数えるのではなく、next がある限りページの取得を続けてください。

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

お気に入りと評価

自分の生成には、2 つの印を付けておけます。どちらもすべてのジョブで読み取れ、一覧のフィルターとして使えます。

  • お気に入りは、ジョブに付けるブックマークです。自分のジョブならステータスを問わず、ほかの人のジョブならギャラリーにある公開済みの完了したジョブに付けられます。
  • 評価は、自分のジョブに対する判定で、good または bad です。

自分のジョブには、独自の名前である タイトル も付けられます。たとえば画像、クリップ、トラック、音声のテイクに「Wedding toast, final」(結婚式の乾杯、最終版)と付けます。

メソッドパスボディまたはクエリ内容
PUT/v1/jobs/:id/rating{ "rating": "good" | "bad" | null }自分のジョブを評価するか、null で評価をクリアします。rating は必須なので、クリアは明示的に行います。{ data: { jobId, rating } } を返します。
PATCH/v1/jobs/:id{ "title": string | null }自分のジョブに名前を付けるか、null または "" で名前を消します。{ data: { jobId, title } } を返します。
POST/v1/gallery/favorite{ "jobId": "..." }ジョブをお気に入りに追加するか、すでにお気に入りなら外します。切り替え後の状態である { favorited } を返します。
GET/v1/gallery/favoritesなしお気に入りに追加したジョブの ID を、新しい順に返します。形式は { data: string[] } です。
GET/v1/gallerytype、userId、favoritesOnly=true、limit(1〜50、デフォルトは 20)、cursor公開ギャラリーを、完了が新しい順に返します。自分の userId と自分のトークンを使うと、favoritesOnly=true で一覧を自分のお気に入りに絞り込めます。 各カードには、所有者が付けたジョブの名前 title が含まれます。名前がなければ null です。
  • すべてのジョブに favorited と rating が含まれます。GET /v1/jobs と GET /v1/jobs/:id で返されます。サーバーが一時的にそれらを読み取れない場合も、ジョブは返されますが、この 2 つのフィールドは省かれます。フィールドがない場合は、false ではなく不明として扱ってください。不明なお気に入りを切り替えると、お気に入りが外れてしまうおそれがあります。
  • 評価はジョブごとに 1 つで、そのジョブの所有者のものです。ほかの人のジョブには 404 not_found が返されます。good、bad、null 以外の評価には 400 validation_error が返されます。
  • ほかの人の非公開のジョブをお気に入りに追加しようとすると 404 not_found が返され、何も保存されません。お気に入りから外す操作は、常に成功します。
  • スコープ:OAuth アプリのトークンでは、2 つの書き込みに assets:write が、お気に入りの一覧表示に assets:read または jobs:read が必要です。ジョブの読み取りは、引き続き jobs:read です。
  • ギャラリーを非表示にしているデプロイメントでは、すべての /v1/gallery ルートに 404 が返されます。
  • 公開作品を許可していないデプロイメントでは、すべての GET /v1/gallery の表示に空のページ { data: [], nextCursor: null, totalCount: 0 } が返されます。ただし自分の作品は別で、自分の userId と自分のトークンを使えば、引き続き一覧表示できます。そこでは、POST /v1/gallery/favorite で追加できるのは自分のジョブだけで、他人のジョブには 404 not_found が返されます。お気に入りの削除は常にできます。ギャラリーの報告ルート POST /v1/gallery/report は、すべての項目に 404 not_found を返します。
  • タイトルはプレーンテキスト 1 行で、1〜120 文字、言語は問いません。前後の空白は取り除かれます。それ以外は 400 validation_error になります。名前を付けられるのはジョブの所有者だけで、ほかの人のジョブには 404 not_found が返されます。名前の付与は無料で、ゴミ箱の中も含め、あらゆる種類とステータスのジョブで使えます。ジョブのほかの部分は何も変わりません。OAuth アプリのトークンには assets:write が必要です。
  • タイトルは、ジョブが返されるすべての場所で title として読み取れます:GET /v1/jobs/:id、GET /v1/jobs、セッションの項目、GET /v1/trash、ギャラリーのカード(プロンプトの横に公開)、ライブラリの行です。ライブラリの行では、title はファイルを作ったジョブの名前で、filename ではありません。
# Rate a job good, favorite it, then list your good favorites that completed
curl -s -X PUT "https://app.nodaro.ai/v1/jobs/$JOB/rating" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": "good"}'
curl -s -X POST "https://app.nodaro.ai/v1/gallery/favorite" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"jobId\": \"$JOB\"}"
curl -s "https://app.nodaro.ai/v1/jobs?rating=good&favorited=true&status=completed" \
  -H "Authorization: Bearer $NODARO_API_KEY" | jq '.data[] | {id, favorited, rating}'

編集した画像の記録

自分のアプリで編集した画像(たとえば、切り抜き、書き込み、フィルターをかけたもの)は、ジョブではなくアップロードです。そのままでは、評価、お気に入りへの追加、セッションへの保存、ジョブ ID を受け取るツールへの受け渡しができません。ジョブとして記録してください。

  1. POST /v1/upload で編集した画像を保存し、その assetId を控えておきます。アップロードを参照してください。
  2. 任意で、POST /v1/upload-json でエディターのデザインの状態を保存すると、編集をもう一度開けるようになります。このルートは 25 MB までの任意の JSON ボディを受け取り、{ url } を返します。
  3. { assetId, sourceJobId?, sourceImageUrl?, sourceAssetId?, editStateUrl?, sessionId? } で POST /v1/jobs/from-upload を呼び出します。

このルートは、アップロードを、すぐに完了する image-edit ジョブとして記録し、{ data: Job } を返します。画像を記録した場合は 201 を、この assetId が以前に記録済みの場合は同じジョブで 200 を返します。

  • 無料で非公開。ジョブの記録には何も課金されません。ファイルのストレージは、アップロードしたときに計上済みだからです。このジョブが公開されることはありません。自分のジョブ履歴、ギャラリー、ライブラリの表示には並びますが、公開ギャラリーには並びません。
  • 含まれる内容。output_data.imageUrl はアップロードで、thumbnailUrl、width、height が付きます。input_data には、type: "image-edit"、assetId、ソース(sourceJobId または sourceAssetId)と、ソースの画像である sourceImageUrl が含まれます。複数の画像を作ったジョブの場合は、編集した画像を sourceImageUrl として送ってください。キャラクター、オブジェクト、クリーチャー、ロケーションの画像を編集したものは、そのつながりを保つので、そのアセットと一緒に並びます。GET /v1/jobs?type=image-edit でこれらのジョブを一覧表示できます。
  • 1 つのアップロードに 1 つのジョブ。同じ assetId には同じジョブが返されるので、再試行やダブルクリックで 2 つ作られることはありません。再試行は、以前の試行で終わらなかったジョブも完了させるので、2xx の応答には必ず完了したジョブが含まれます。ジョブは、それを作成したリクエストのソース、デザインの状態、セッションを保持します。再試行で送った値は適用されません。ジョブを 2 つ目のセッションに表示するには、POST /v1/sessions/:id/items でそのセッションに追加します。
  • 拒否。アセット、ソース、セッションが自分のものでない場合は 404 not_found です。アセットが画像でない場合や、自分が保存したファイルでない場合は 400 validation_error です。ソースのジョブに完成した画像がない、sourceImageUrl がその画像のどれでもない、両方のソースが送られた、または editStateUrl が POST /v1/upload-json の返した URL でない場合も、同じエラーになります。image-edit:<assetId> をすでに別のリクエストの Idempotency-Key として使っていた場合は 409 conflict です。デプロイ環境のジョブポリシーが画像を拒否した場合は、どの再試行でも 422 job_blocked です。
  • 削除。ジョブを削除しても、アップロードしたファイルはアップロードに残ります。ライブラリからアップロードを削除しても、このジョブが表示している間はファイルが保持されます。

OAuth アプリのトークンには assets:write が必要です。

# Record an edited image next to the job it was made from, in a session
curl -s -X POST "https://app.nodaro.ai/v1/jobs/from-upload" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"assetId\": \"$ASSET\", \"sourceJobId\": \"$JOB\", \"sessionId\": \"$SESSION\"}" | jq '.data | {id, status, output_data}'

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

次の 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\"]}"

レスポンスは { "data": [ … ] } で、各ジョブの id、status、output_data、error_message、error_hint が含まれます。credit_status は含まれません。

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

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

POST /v1/jobs/:id/cancel は、ジョブをキャンセルし、確保していたクレジットを解放します。レスポンスは { "success": true, "cancelled": 1 } です。pending_review で保留中のジョブもキャンセルできます。ジョブをキャンセルすると、まだ実行中の子ジョブもキャンセルされます。完了済みの子ジョブはそのまま残り、すでにモデルに送られた子ジョブは、処理中のほかのジョブと同じように最後まで実行されます。

従量課金の LLM ジョブのキャンセル:言語モデルのジョブは、その呼び出しで使ったトークンに応じて課金されるため、キャンセルの結果は、呼び出しが始まっているかどうかで変わります。

  • 呼び出しが始まったジョブに POST /v1/jobs/:id/cancel を送ると、{ "success": true, "cancelled": 0, "inFlight": true } が返ります。ジョブは最後まで実行され、使ったクレジットだけが請求されます。
  • キャンバスの停止、POST /v1/jobs/cancel-all、ワークフローのキャンセル(POST /v1/workflow-executions/:id/cancel)は、ジョブをキャンセルします。プロバイダーがすでに課金した分が請求され、確保額の残りは返還されます。
  • 呼び出しが始まる前に止められたジョブは、どの方法でキャンセルしても返還されます。例外は、同じジョブの以前の試行ですでに使った分(たとえば、課金された試行の後の再試行)で、その使用分は請求されます。

DELETE /v1/jobs/:id は、ジョブをゴミ箱に移し、{ "success": true } を返します。ジョブを削除できるのは、その所有者だけです。実行中のジョブは削除後も実行を続けるので、処理を止めたい場合は、先にキャンセルしてください。ジョブを削除しても、クレジットは返還されません。OAuth アプリがジョブを削除または復元するには、assets:write スコープが必要です。

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/sessions/:id/items/:jobId/restore で復元するか、DELETE /v1/sessions/:id/items/:jobId?forever=true で完全に削除するまで残ります。外してもジョブは削除されません。有効なセッションのどこにもないアイテムは、一般に表示されます。
  • 削除したジョブは、すべての読み取りから消えます。ジョブの一覧と ID による読み取り、ステータスのポーリング、ギャラリー、セッションのフィードとプレビュー、MCP ツール、CLI です。削除から 30 日間は復元できます。POST /v1/jobs/:id/restore は、ジョブが入っていたすべてのセッションにジョブを戻します。
  • 30 日が過ぎると、削除したジョブは、その非公開のメディアとともに完全に削除されます。ライブラリに保存したコピーは残ります。
  • 今すぐ完全に削除する:DELETE /v1/jobs/:id?forever=true は、すでにゴミ箱にあるジョブを完全に削除します。ゴミ箱にないジョブには 409 not_in_trash を返します。
  • ジョブを削除しても、完全に削除しても、クレジットは返還されません。

GET /v1/trash は、ゴミ箱の中身を新しい順に、1 ページずつ返します(limit は 1〜100、デフォルトは 50、それに cursor)。各エントリーは、{ kind: "removed", removedAt, session: { id, title, projectId }, job } または { kind: "deleted", deletedAt, purgeAt, job } のどちらかです。外したアイテムのジョブも削除した場合、そのエントリーは削除したジョブとして 1 回だけ表示されます。

クエリ意味
projectIdプロジェクト ID を指定すると、そのプロジェクトのセッションから外したアイテムと、そのプロジェクトのセッションが保持していた削除済みのジョブになります。none を指定すると、プロジェクトのないセッションと一般が対象になります。
toolその作成ツールのセッションが保持している、または保持していたものです。どのセッションにも入ったことがないジョブにはツールがないので、tool では除外されます。
typeジョブの input_data.type をカンマ区切りで指定します。一度もセッションに入らなかった削除済みのジョブも含めるには、自分のツールのジョブの種類を指定して、type だけで絞り込みます。

セッションを削除すると、そのセッションから外したアイテムも削除されます。

コンポーネントの実行

POST /v1/component/execute は、保存したコンポーネントをバックグラウンドで実行し、{ jobId } とともに 202 を返します。このジョブは、ほかのジョブと同じようにポーリングします。公開作品を許可しないデプロイメントでは、自分のコンポーネントか、そのコンポーネントを含むワークフローの完全な実行の中のコンポーネントだけを実行します。それ以外の呼び出しには 404 not_found「Component not found」が返されます。OAuth アプリのトークンでは、このルートに workflows:execute スコープが必要で、後述の待機時間の上限の読み取りには jobs:read が必要です。サーバーは、コンポーネントの実行に 90 分を割り当て、さらに、その中にある時間のかかるレンダリングの時間枠を加えます。たとえば、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 を参照してください。

よくある質問

Nodaro API のジョブとは何ですか?

ジョブは、1 枚の画像、1 本の動画のレンダリング、1 つの音声クリップなど、生成の 1 単位です。POST /v1/<node-type> を呼び出すとジョブ ID が返り、ワークフローの実行では、実行する AI ノードごとに 1 つのジョブが作成されます。

Nodaro のジョブは、どのくらいの間隔でポーリングすればよいですか?

2〜5 秒ごとです。ジョブの状態は、ミリ秒単位ではなく秒単位で変わります。多くのジョブを追跡するには、1 回の呼び出しで最大 100 件のジョブを返す GET /v1/jobs/status または POST /v1/jobs/batch-status を使います。

pending_review というステータスは、どういう意味ですか?

デプロイ環境が、結果を公開する前に、人によるレビューのために保留していることを示します。ジョブはまだ処理中で、クレジットは確保されたままです。ポーリングを続けてください。ジョブは最終的に completed、failed、cancelled のいずれかになります。

失敗したジョブのクレジットが返還されたかどうかは、どうすればわかりますか?

GET /v1/jobs/:id または GET /v1/jobs/:id/status で credit_status を確認します。値は reserved、committed、refunded のいずれかです。安全フィルターやデプロイ環境のポリシーでブロックされた生成は、必ず返還されます。

ジョブに実際にかかった費用は、どうすればわかりますか?

GET /v1/jobs または GET /v1/jobs/:id で credits_charged を確認します。これは、確保した額が精算された後にジョブにかかった費用で、ジョブが実行したステップも含みます。確保した額より少ないことがあります。ジョブ自身の確保がまだ開いているあいだは null です。

API でジョブを評価したり、お気に入りに追加したりできますか?

はい。PUT /v1/jobs/:id/rating は、自分のジョブに good、bad、null のいずれかを設定し、POST /v1/gallery/favorite はお気に入りを切り替えます。GET /v1/jobs では、rating= と favorited= でその両方を絞り込めます。

最終更新

目次