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

ジョブと実行

TypeScript から Nodaro の実行をポーリング、一覧表示、評価、キャンセル、削除し、ワークフローの実行を追跡して、ジョブの終了時に署名付きの Webhook の呼び出しを受け取ります。

ジョブは、1 枚の画像、1 本の動画のレンダリング、1 つのナレーションなど、Nodaro での生成 1 件です。実行は、ワークフロー全体を 1 回実行したものです。client.jobs はジョブの読み取り、一覧表示、キャンセル、削除を行い、client.executions はワークフローの実行の読み取り、一覧表示、キャンセルを行います。client.webhooks は、ジョブが終わったときに Nodaro が呼び出すエンドポイントを登録します。client.videoPro は、長時間の動画生成 Proの実行を停止または継続します。これらのメソッドは、ジョブと実行の REST API と同じエンドポイントを呼び出します。

メソッド

メソッド内容
executions.get(id)ワークフローの実行を、すべてのノードの状態とともに読み取ります
executions.listForWorkflow(workflowId, params?)ワークフローの実行を一覧表示します
executions.cancel(id, params?)ワークフローの実行を停止します
jobs.get(id)ジョブを、その入力と出力とともに読み取ります
jobs.list(params?)自分のジョブを、新しい順に一覧表示します
jobs.rate(id, rating)自分のジョブを良いまたは悪いと評価するか、評価を消去します
jobs.rename(id, title)自分のジョブに名前を付けるか、名前を消します
jobs.fromUpload(params)ブラウザーで編集した画像を、ジョブとして記録します
jobs.getStatus(id)ポーリング用に、ジョブのステータスを読み取ります
jobs.cancel(id)ジョブを停止し、確保されていたクレジットを返還します
jobs.delete(id, options?) と jobs.restore(id)ジョブをゴミ箱に移す、戻す、または完全に削除します
webhooks.create(input) ほかジョブが終わったときに Nodaro が呼び出すエンドポイントを、登録、変更、テスト、監査します
verifyWebhookSignature(options)エンドポイントが受け取った呼び出しの署名を確認します
videoPro.stop(jobId)動画生成 Pro の実行を停止し、完成した部分を残します
videoPro.continueRun(jobId, opts?)動画生成 Pro の実行を、新しいジョブとして継続します

ステータス

ジョブは、次のステータスを移り変わります。

ジョブのステータス意味
pending、queuedワーカーを待っています。
processing実行中です。モデルが報告する場合、progress が 0 から 100 まで変化します。
pending_reviewこのデプロイ環境のコンテンツポリシーにより、人によるレビューのために保留されています。終了状態ではありません。
completed完了しました。結果は output_data にあります。
failed失敗しました。理由は error_message に示され、error_hint が分類する場合もあります。
cancelledキャンセルによって停止しました。

実行には、独自のステータスがあります。pending、running、completed、failed、cancelled、stopping、timed_out、discarded です。実行内の各ノードは、pending、running、completed、failed、skipped のいずれかです。

client.executions

実行は、ワークフローを 1 回実行したものです。AI ノードごとの 1 つのジョブと、すべてのノードの状態をまとめます。

executions.get(id)

ワークフローの実行を、すべてのノードの状態のマップを含めて読み取ります。id がワークフローの実行ではなく単体のノードのジョブを指す場合、サーバーは、その 1 つのノードについて同じ形式で応答します。

get(id: string): Promise<{ data: WorkflowExecution }>

プロパティ

型

const { data } = await client.executions.get(executionId)
console.log(data.status, `${data.completedNodes}/${data.totalNodes}`, data.totalCreditsUsed)

WorkflowExecution は、id、kind、workflowId、status、outcome、triggerType(manual、webhook、schedule、app_run、single-node、telegram、telegram_account、api、mcp のいずれか)、nodeStates、totalNodes、completedNodes、failedNodes、totalCreditsUsed、errorMessage、startedAt、completedAt、createdAt、updatedAt を持ちます。kind は、ワークフローの実行では execution、単一ノードのジョブでは job です。MCP クライアントが開始した単一ノードのジョブの triggerType は mcp です。

新しいものが見つからなかった実行。 新しいものが見つからなかった実行は、failed ではなく completed で終わります。たとえば、フィードに新しい投稿がなく、その後のライターに書く内容がなかった場合です。テキストを必要とするノードで、接続されたテキストがこの実行で何も作らなかったノードから来ている場合、そのノードは nodeStates[id].skipReason を "empty_input" にしてスキップされます。完了した実行は outcome: "nothing_new" になります。それ以外の完了した実行は outcome: "succeeded" です。実行が完了するまで outcome はありません。

import { executionOutcome, countEmptyInputSkips } from "@nodaro/sdk"

const { data } = await client.executions.get(executionId)
if (data.outcome === "nothing_new") {
  console.log(`Nothing new: ${countEmptyInputSkips(data.nodeStates)} node(s) had nothing to work on`)
}
executionOutcome(data.status, data.nodeStates) // the same answer, worked out in your code

ノードの出力を読み取る。nodeStates[nodeId].output は、ノードが completed のときに存在します。3D シーンのノードのように、ノードが failed でも、実行が使える結果を残す場合には存在することもあります。ステータスではなくこのフィールドを確認し、output が存在することを成功と見なさないでください。

import { nodeStateMayCarryOutput } from "@nodaro/sdk"

const node = data.nodeStates["scene-1"]
if (node.status === "failed") {
  console.error(node.error) // the failure stands
  if (node.output?.plan) {
    // the draft the run kept is still here, and it was billed
  }
}
nodeStateMayCarryOutput(node.status) // true for "completed" and "failed"

この 2 つのステータスの集合である OUTPUT_BEARING_NODE_STATUSES も、エクスポートされています。

executions.listForWorkflow(workflowId, params?)

1 つのワークフローの実行を、新しい順にページ単位で一覧表示します。この一覧には、そのワークフロー上で開始された単体ノードの実行も含まれます。

listForWorkflow(workflowId: string, params?: ListExecutionsForWorkflowParams): Promise<{
  data: WorkflowExecutionSummary[]
  nextCursor?: string
}>

プロパティ

型

const { data: runs, nextCursor } = await client.executions.listForWorkflow(workflowId, {
  limit: 20,
  status: "completed",
})

各 WorkflowExecutionSummary は、get() と同じ kind と outcome を持ちます。

executions.cancel(id, params?)

ワークフローの実行を停止します。停止のしかたは、次の 3 通りです。

  • 即時(デフォルト):実行中のジョブがキャンセルされ、確保されていたクレジットが返還され、ステータスは cancelled になります。実行中の従量課金の LLM ジョブもキャンセルされますが、プロバイダーがすでに課金した分が請求され、確保額の残りは返還されます。呼び出しが始まる前に止められたジョブは返還されます。ただし、同じジョブの以前の試行ですでに使った分は除きます。
  • mode: "after_current":ステータスは stopping になります。実行中のノードは完了してキャンバスとライブラリに反映され、その後で実行が停止します。
  • mode: "discard":新しいノードは開始しませんが、実行中のジョブはキャンセルされません。外部のモデルの呼び出しは、途中で止められないためです。それらは完了してライブラリに保存されますが、結果はキャンバスには戻りません。ステータスは discarded になります。ジョブは完了しているため、返還は行われません。
cancel(id: string, params?: { mode?: "after_current" | "discard" }): Promise<{ success: true }>

プロパティ

型

await client.executions.cancel(executionId, { mode: "after_current" })

client.jobs

ジョブは、1 枚の画像、1 本の動画のレンダリング、1 つのナレーションなど、生成 1 件です。ワークフローの実行は AI ノードごとに 1 つのジョブを作り、単体のノードの実行もそれぞれ 1 つのジョブを作ります。ジョブのフィールドは、API が送るとおりのスネークケースです。

jobs.get(id)

ジョブを、その入力と出力を含めて読み取ります。

get(id: string): Promise<{ data: Job }>

プロパティ

型

const { data: job } = await client.jobs.get(jobId)
if (job.status === "completed") console.log(job.output_data)

Job には、次のフィールドがあります。

フィールド説明
id、status、progressジョブの id、ステータス、0 から 100 までの進行状況です。
input_data、output_dataリクエストの内容と結果です。どちらからも、サーバー内部専用の値は取り除かれます。
error_messageジョブが失敗した理由、または null です。
error_detail失敗についてのプロバイダー自身の説明です。リンクはホスト名までに切り詰められ、秘密情報は取り除かれています。説明がない失敗では null です。開けないワークフローの実行のジョブ(実行した他人の共有リンクや公開アプリなど)でも null です。デプロイメントがこの説明を管理者だけに限定している場合も null です。error_message の横に表示し、分岐には error_hint を使ってください。
error_hint一部の失敗について、構造化された理由を示します。下記を参照してください。
creditsジョブのために確保されたクレジット、または null です。
credit_statusreserved、committed、refunded のいずれかで、クレジットの状態を示します。課金がないジョブでは null です。
credits_charged確保した額が精算された後にジョブにかかった費用で、ジョブが実行したステップも含みます。ほかのジョブを代わりに実行するジョブ(たとえば、Video Remake の実行のリファレンスの準備、マスク、動画)は、各ステップが精算された時点でそのステップの分も課金されます。確保した額より少ないことがあります。実行自身の確保が返還された場合は、0 に精算済みのステップの額を足したものです。ジョブ自身の確保が開いているあいだ(一部のステップが精算済みでも)、実行の中で何も確保されなかった場合、ステップを一時的に読み取れない場合は null です。利用額を合計するには、このフィールドを足し合わせてください。
credits_held実行全体の確保額で、credits にステップの確保額を足したものです。
credits_released実行の中のすべての確保が精算された後に、credits_held から戻った額です。それまでは null です。
job_typeジョブの種類です。
created_at、started_at、completed_atタイムスタンプです。
user_id所有者です。
source、source_detailジョブの発信元です。sdk、cli、mcp、app、web、api などがあり、sdk/2.17.0 のような詳細が付きます。
recoveringモデルが結果を返した後にワーカーが停止したジョブを、プラットフォームが復旧している間 true になります。
favoritedジョブのオーナーがお気に入りにしたかどうかです。client.gallery を参照してください。
rating"good"、"bad"、null のいずれかです。jobs.rate() を参照してください。
title自分で付けたジョブの名前です。名前を付けるまでは null です。jobs.rename() を参照してください。
session_idジョブが作成された生成セッション、または null です。

サーバーは、favorited と rating を一時的に読み取れない場合、それらを含めません。フィールドがない場合は、false ではなく不明として扱ってください。

画像のジョブの output_data には、画像のピクセルサイズが入ります。imageUrl の width と height、そして imageUrls の横に images(エントリーごとの { url, width, height })です。古いジョブには、これらのフィールドはありません。Job.output_data の型は unknown なので、型付きで読み取るには NodeJobOutput にキャストしてください。runAndWait() を参照してください。

error_hint には、5 種類あります。まず kind で絞り込んでから、残りを読んでください。

  • safety-block:モデル自身の安全フィルターが、出力を拒否しました。class は copyright、likeness、safety のいずれかです。retried は、Nodaro がすでに 1 回再試行したかどうかを示し、suggestedProvider は、存在する場合、同じリクエストを再試行できるモデルの名前を示します。subject: "input_video" は、存在する場合、プロバイダーがジョブの入力動画そのものを拒否したことを意味します。別のクリップを送ってください。copyright のブロックでの subject: "input_image" は、プロバイダーが入力画像のいずれかを、著作権で保護されている可能性があるとして拒否したことを意味します。別の画像を送ってください。subject: "prompt" は、プロバイダー自身の文面がプロンプトを挙げたことを意味します。プロンプトを変えてください。subject: "audio" は、画像ではなく生成されたオーディオが原因とされたことを意味します。モデルがプロンプトをブロックした場合を参照してください。
  • policy-block:このデプロイ環境のコンテンツポリシーが、リクエストまたは結果を拒否しました。reason はユーザー向けに書かれているため、そのまま表示してください。
  • credits:自分のクレジットを確保するステップが拒否されたために、ジョブが途中でクレジット不足になりました(たとえば、Video Remake やトレンドの実行が開始する動画)。code は拒否のコードで、insufficient_credits、または free_video_limit や budget_exceeded などのプランやワークスペースの上限です。不明なコードは insufficient_credits と同じように扱ってください。ジョブのクレジットは返還されます。クレジットの追加か上限の引き上げをユーザーに依頼してから、もう一度実行してください。
  • input-refused:プロバイダーが、コンテンツポリシーの分類を示さずに、ジョブの入力動画を拒否しました。subject は "input_video" です。ほかのモデルは提案されません。別のクリップを送ってください。
  • request-refused:プロバイダーが、送られたままのリクエストを拒否し、設定、ファイルの形式やサイズ、プロンプトの長さなど、その不備を示しました。同じリクエストはまた拒否されます。入力画像、動画、プロンプト、または設定を変えてください。subject: "input_video" がある場合は、長さやサイズ、キャラクターが見つからないなど、プロバイダーの文面が入力動画を不備として挙げています。別のクリップを送ってください。コンテンツポリシーによるブロックではありません。Video Remake やトレンドの実行では、1 つのステップの拒否です。

jobs.list(params?)

自分のジョブを、新しい順にページ単位で一覧表示します(GET /v1/jobs)。

list(params?: ListJobsParams): Promise<{
  data: Job[]
  next: string | null
}>

プロパティ

型

let cursor: string | undefined
do {
  const page = await client.jobs.list({ type: "llm-structured", origin: "my-app", cursor })
  for (const job of page.data) console.log(job.id, job.status)
  cursor = page.next ?? undefined
} while (cursor)

どのフィルターも、ほかのフィルターと組み合わせられます。ページに含まれる行は limit より少ないことがあり、0 行でも next が付くことがあります。行数ではなく、next を基準にページを進めてください。

// Your favorited images and videos that came out well
const { data: keepers } = await client.jobs.list({
  type: ["generate-image", "generate-video"],
  status: "completed",
  favorited: true,
  rating: "good",
})

jobs.rate(id, rating)

自分のジョブを "good" または "bad" と評価するか、null で評価を消去します(PUT /v1/jobs/:id/rating)。ジョブの評価は 1 つで、評価できるのはオーナーだけです。ほかの人のジョブでは、NotFoundError がスローされます。

rate(id: string, rating: "good" | "bad" | null): Promise<{ data: { jobId: string; rating: "good" | "bad" | null } }>

プロパティ

型

await client.jobs.rate(jobId, "good")
await client.jobs.rate(jobId, null) // clear it

評価は Job.rating として読み取れ、jobs.list() の絞り込みに使えます。OAuth アプリには assets:write スコープが必要です。評価機能のないサーバーでは、コード not_available、ステータス 503 の NodaroError がスローされます。

jobs.rename(id, title)

自分のジョブに名前を付けるか、null で名前を消します(PATCH /v1/jobs/:id)。画像、クリップ、トラック、音声のテイクに「Wedding toast, final」(結婚式の乾杯、最終版)のような名前を付けるのに使います。名前を付けられるのはジョブの所有者だけです。ほかの人のジョブでは NotFoundError がスローされます。

rename(id: string, title: string | null): Promise<{ data: { jobId: string; title: string | null } }>

プロパティ

型

await client.jobs.rename(jobId, "Hero shot v2")
await client.jobs.rename(jobId, null) // clear it
  • 名前の前後の空白は取り除かれます。 長すぎる名前や複数行の名前では、コード validation_error の NodaroError がスローされます。
  • 名前の付与は無料で、ゴミ箱の中も含め、あらゆる種類とステータスのジョブで使えます。ジョブのほかの部分は何も変わらず、結果の順序もそのままです。
  • 名前は get()、list()、セッションの項目、client.trash.list() で Job.title として読み取れます。ギャラリーのカードでは title としてプロンプトの横に公開され、ライブラリの行でも title になります。ライブラリの行では、ファイルを作ったジョブの名前で、filename ではありません。
  • OAuth アプリには assets:write スコープが必要です。

jobs.fromUpload(params)

ブラウザーで編集した画像を、ジョブとして記録します(POST /v1/jobs/from-upload)。先に uploads.upload で編集した画像を保存してください。結果は、完了済みで非公開かつ無料の image-edit ジョブで、その output_data.imageUrl がアップロードです。その後は、ほかの画像のジョブと同じように、評価、お気に入りへの追加、list({ type: "image-edit" }) での一覧表示、セッションへの保存ができます。

fromUpload(params: JobFromUploadParams): Promise<{ data: Job }>

プロパティ

型

const upload = await client.uploads.upload(editedPng)
const { url: editStateUrl } = await client.uploads.uploadJson(designState)
const { data: job } = await client.jobs.fromUpload({
  assetId: upload.assetId!,
  sourceJobId,
  editStateUrl,
  sessionId,
})

1 つのアップロードは 1 つのジョブです。同じ assetId には同じジョブが返されるので、再試行で 2 つ作られることはありません。キャラクター、オブジェクト、クリーチャー、ロケーションの画像を編集したものは、そのつながりを保ちます。OAuth アプリには assets:write スコープが必要です。

  • NotFoundError:アセット、ソース、セッションが自分のものではありません。
  • コード validation_error の NodaroError:アセットが自分の保存した画像ではないか、ソースに完成した画像がありません。
  • JobBlockedError:デプロイ環境のジョブポリシーが画像を拒否しました。 ブラウザーで編集した画像の記録を参照してください。

jobs.getStatus(id)

ジョブのステータスだけを読み取ります。id、status、progress、output_data、error_message、error_detail、error_hint、credit_status、completed_at です。completed_at は、ジョブが完了した日時(サーバーの時計による)で、完了するまでは null です(GET /v1/jobs/:id/status)。リクエストのデータと料金のフィールドを省くため、get() よりもずっと軽量です。ポーリングのループで使ってください。

getStatus(id: string): Promise<{ data: JobStatusResult }>

プロパティ

型

async function waitForJob(jobId: string) {
  for (;;) {
    const { data } = await client.jobs.getStatus(jobId)
    if (data.status === "completed") return data.output_data
    if (data.status === "failed" || data.status === "cancelled") {
      throw new Error(data.error_message ?? data.status)
    }
    await new Promise((resolve) => setTimeout(resolve, 2_000))
  }
}

client.nodes.runAndWait() は、進行状況、キャンセル、型付きエラーとともに、このループを代わりに実行します。

jobs.cancel(id)

ジョブをキャンセルし、確保されていたクレジットを返還します。レビューのために保留されているジョブも、キャンセルできます。

cancel(id: string): Promise<{ success: true; cancelled: number; inFlight?: boolean }>

実行中の従量課金の LLM ジョブは例外です。呼び出しがすでに始まっている場合、キャンセルは { success: true, cancelled: 0, inFlight: true } を返します。ジョブは最後まで実行され、使った分だけが請求されます。呼び出しが始まる前に止められたジョブは返還されます。ただし、同じジョブの以前の試行ですでに使った分(たとえば、課金された試行の後の再試行)は除きます。

プロパティ

型

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

jobs.delete(id, options?) と jobs.restore(id)

delete は、ジョブをゴミ箱に移します(DELETE /v1/jobs/:id)。それ以降、どの読み取りにもそのジョブは含まれません。ジョブは 30 日間復元でき、その後、非公開のメディアとともに完全に削除されます。ライブラリに保存したコピーは残ります。restore(POST /v1/jobs/:id/restore)は、ジョブが入っていたすべてのセッションにジョブを戻します。{ forever: true } を付けると、すでにゴミ箱にあるジョブを今すぐ完全に削除します。ゴミ箱にないジョブでは、コード not_in_trash(ステータス 409)の NodaroError を投げます。

削除または復元できるのは、ジョブの所有者だけです。実行中のジョブは削除後も実行を続けるため、ワーカーを止めたい場合は、先にキャンセルしてください。クレジットは返還されません。OAuth アプリには assets:write スコープが必要です。どちらのメソッドも { success: true } を返します。

delete(id: string, options?: { forever?: boolean }): Promise<{ success: true }>
restore(id: string): Promise<{ success: true }>

プロパティ

型

await client.jobs.delete(jobId)                   // to the Trash
await client.jobs.restore(jobId)                  // undo
await client.jobs.delete(jobId, { forever: true }) // after a delete: gone for good

削除したジョブが jobs.list() に表示されることはありません。そのジョブは client.trash にあります。

client.webhooks

送信 Webhook は、ジョブが終わったことをサーバーに知らせるので、アプリがポーリングする必要がありません。https のエンドポイントを登録すると、Nodaro はアカウントのすべての job.completed と job.failed について、そのエンドポイントに POST を送ります。各呼び出しは、エンドポイント固有のシークレットで署名されます。失敗した呼び出しは、間隔を空けながら約 43 時間再試行され、すべての試行がエンドポイントの配信ログに残ります。イベント、ボディ、ヘッダー、再試行のスケジュールについては、Webhook を参照してください。

OAuth アプリのトークンには jobs:read スコープが必要です。接続済みのアプリが登録したエンドポイントは、そのアプリ自身が送信したジョブだけを受け取ります。

create(input: CreateWebhookEndpointInput): Promise<CreatedWebhookEndpoint>      // { data, secret }
list(): Promise<{ data: WebhookEndpoint[] }>
get(id: string): Promise<{ data: WebhookEndpoint }>
update(id: string, input: UpdateWebhookEndpointInput): Promise<{ data: WebhookEndpoint }>
delete(id: string): Promise<{ success: true }>
rotateSecret(id: string, input?: RotateWebhookSecretInput): Promise<RotatedWebhookSecret>   // { secret, previousSecretExpiresAt }
deliveries(id: string, params?: ListWebhookDeliveriesParams): Promise<WebhookDeliveryPage>
getDelivery(id: string, deliveryId: string): Promise<{ data: WebhookDelivery }>
test(id: string): Promise<{ data: WebhookDelivery }>

webhooks.create(input)

エンドポイントを登録し、その secret(whsec_…)とともに返します。シークレットは一度だけ表示されるので、サーバーの設定と一緒に保存してください。

プロパティ

型

const { data: endpoint, secret } = await client.webhooks.create({
  url: "https://example.com/nodaro-webhook",
  events: ["job.completed", "job.failed"],
})
await client.webhooks.test(endpoint.id) // sends a ping

1 つのアドレスには、1 つのエンドポイントしか作れません(409 url_taken)。1 つのアカウントのエンドポイントは最大 10 個です(400 limit_reached)。

webhooks.update(id, input)

url、events、description(null で消去)、isActive のいずれかを変更します。50 回連続で配信が最終的に失敗すると、Nodaro はエンドポイントを無効にし、disabledReason を "consecutive_failures" に設定します。isActive: true にすると再び有効になり、consecutiveFailures がリセットされます。

webhooks.rotateSecret(id, input?)

新しいシークレットを作成し、一度だけ返します。以降のすべての配信は、再試行も含めて新しいシークレットで署名されます。古いシークレットも、gracePeriodSeconds(0〜604800、デフォルトは 1 日)の間は並行して署名に使われるので、受信側を途切れなく更新できます。その間、Nodaro-Signature には 2 つ目の v1= が入り、verifyWebhookSignature はどちらも受け付けます。漏れたシークレットをすぐに無効にするには、{ gracePeriodSeconds: 0 } を渡してください。

const { secret, previousSecretExpiresAt } = await client.webhooks.rotateSecret(endpoint.id)

古いシークレットがすぐに無効になった場合、previousSecretExpiresAt は null です。

webhooks.deliveries(id, params?) と getDelivery(id, deliveryId)

deliveries() は、配信ログを新しい順に読み取ります。ログは 30 日間保持されます。status("pending"、"delivered"、"failed")で絞り込み、limit(1〜100、デフォルトは 20)と cursor でページを進めます。getDelivery() は、ID で 1 件の配信を読み取ります。

各 WebhookDelivery は、event、jobId、status、attempts、responseStatus、responseBody(最初の 2 KB)、durationMs、error、requestBody、nextAttemptAt、deliveredAt を持ちます。requestBody は送信したとおりのボディで、配信が成功すると null になります。

webhooks.test(id)

ping をキューに入れ、その配信を返します。ping は数秒以内に送信され、エンドポイントが無効になっていても、1 回だけ試行されます。getDelivery(id, delivery.id) で追跡してください。

verifyWebhookSignature(options)

エンドポイントが受け取った呼び出しを確認し、パースしたイベントを返します。client のメソッドではなく、@nodaro/sdk のトップレベルのエクスポートです。Web Crypto だけを使うので、Node 20 以降、Deno、Bun、Cloudflare Workers、Vercel Edge、ブラウザーで動作します。

verifyWebhookSignature(options: {
  payload: string | Uint8Array | ArrayBuffer   // the raw body, as received
  header: string | readonly string[] | null | undefined   // Nodaro-Signature
  secret: string                               // whsec_…
  toleranceSeconds?: number                    // default 300; 0 turns the check off
}): Promise<WebhookEvent>

生のボディを受け取ったとおりに渡してください。パースしてから再びシリアライズした JSON は使わないでください。イベントは、data.job が Job である JobWebhookEvent、または PingWebhookEvent です。確認に失敗すると、missing_header、malformed_header、signature_mismatch、timestamp_outside_tolerance、invalid_payload、missing_secret、crypto_unavailable のいずれかのコードを持つ WebhookSignatureError がスローされます。比較は一定時間で行われます。

import { verifyWebhookSignature, WebhookSignatureError } from "@nodaro/sdk"

export async function POST(request: Request) {
  try {
    const event = await verifyWebhookSignature({
      payload: await request.text(),
      header: request.headers.get("nodaro-signature"),
      secret: process.env.NODARO_WEBHOOK_SECRET!,
    })
    if (event.type === "job.completed") await saveResult(event.data.job)
    return new Response(null, { status: 204 })
  } catch (err) {
    if (err instanceof WebhookSignatureError) return new Response(err.code, { status: 400 })
    throw err
  }
}

10 秒以内に 2xx のステータスで応答すると、その配信は配信済みとみなされます。ボディの id は配信の ID で、再試行のたびに同じなので、すでに処理したイベントをスキップするのに使ってください。

client.videoPro

長い動画をセグメントごとにレンダリングするノードである動画生成 Pro の実行制御です。Nodaro Cloud 上で動作します。ほかのノードの実行と同じように実行を開始し、そのジョブに対してこれらのメソッドを使います。

videoPro.stop(jobId)

実行中の動画生成 Pro のジョブを、安全に停止します。処理中のセグメントは破棄されますが、料金は請求され、残りのセグメントはスキップされます。完成したセグメントは、ジョブの最終的な動画としてつなぎ合わされ、使われなかった確保分は返還されます。まだ開始していないジョブは、全額返還のうえキャンセルされます。

stop(jobId: string): Promise<StopVideoProResult>

プロパティ

型

await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // becomes completed, with the partial video

ジョブのポーリングを続けてください。output_data.pro.stopped が true に設定された状態で完了します。

videoPro.continueRun(jobId, opts?)

停止、失敗、完了のいずれかの実行を、新しいジョブとして継続します。fromSegment より前のセグメントは再利用され、それ以降のすべてのセグメントが再生成されます。支払うのは、再生成されるセグメントの分と、Pro の固定料金だけです。

continueRun(jobId: string, opts?: { fromSegment?: number }): Promise<ContinueVideoProResult>

プロパティ

型

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

結果には、ポーリングする新しい jobId が含まれ、continuedFromJobId、fromSegment、segmentCount、deduped が含まれることもあります。

よくある質問

ジョブと実行は、どう違うのですか?

ジョブは、1 枚の画像や 1 本の動画など、生成 1 件を指します。実行は、ワークフロー全体を 1 回実行したもので、AI ノードごとの 1 つのジョブと、すべてのノードの状態をまとめたものです。

ポーリングのループは、どのメソッドを呼び出せばよいですか?

client.jobs.getStatus(jobId) です。ステータス、進行状況、出力、エラーだけを返すため、client.jobs.get よりもずっと軽量です。

ジョブをキャンセルすると、クレジットは返還されますか?

はい。client.jobs.cancel は、ジョブを止め、確保されていたクレジットを返還します。実行を即座にキャンセルした場合も、実行中の各ジョブに対して同じことが行われます。例外は、呼び出しが始まった従量課金の LLM ジョブで、使った分が請求されます。

アプリでポーリングする代わりに、ジョブが終わったときに Nodaro から自分のサーバーを呼び出してもらえますか?

はい。client.webhooks.create で https のエンドポイントを登録します。すると Nodaro は、アカウントのすべての job.completed と job.failed について、署名付きの POST を送ります。各呼び出しは verifyWebhookSignature で確認してください。

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

このデプロイ環境のコンテンツポリシーが、人によるレビューのために結果を保留していることを意味します。終了状態ではありません。ジョブは後で completed、failed、cancelled のいずれかになります。待ち続けて、リクエストを再実行しないでください。

最終更新

目次