ジョブと実行

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

メソッド

ステータス

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

実行には、独自のステータスがあります。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、workflowId、status、triggerType（manual、webhook、schedule、app_run、single-node のいずれか）、nodeStates、totalNodes、completedNodes、failedNodes、totalCreditsUsed、errorMessage、startedAt、completedAt、createdAt、updatedAt を持ちます。

ノードの出力を読み取る。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",
})

executions.cancel(id, params?)

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

• 即時（デフォルト）：実行中のジョブがキャンセルされ、確保されていたクレジットが返還され、ステータスは cancelled になります。
• 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 には、次のフィールドがあります。

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

• safety-block：モデル自身の安全フィルターが、出力を拒否しました。class は copyright、likeness、safety のいずれかです。retried は、Nodaro がすでに 1 回再試行したかどうかを示し、suggestedProvider は、存在する場合、同じリクエストを再試行できるモデルの名前を示します。モデルがプロンプトをブロックした場合を参照してください。
• policy-block：このデプロイ環境のコンテンツポリシーが、リクエストまたは結果を拒否しました。reason はユーザー向けに書かれているため、そのまま表示してください。

jobs.list(params?)

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

list(params?: { type?: string; origin?: string; limit?: number; cursor?: string }): 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 を基準にページを進めてください。

jobs.getStatus(id)

ジョブのステータスだけを読み取ります。id、status、progress、output_data、error_message、error_hint、credit_status です（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 }>

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

jobs.delete(id)

ジョブと、それが生成した非公開のメディアを削除します（DELETE /v1/jobs/:id）。削除できるのは、ジョブの所有者だけです。実行中のジョブはそのまま削除されるため、ワーカーを止めたい場合は、先にキャンセルしてください。

delete(id: string): Promise<{ success: true }>

await client.jobs.cancel(jobId)
await client.jobs.delete(jobId)

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 が含まれることもあります。