ノードの実行

client.nodes は、Nodaro サーバーが対応するノードタイプを一覧表示し、ワークフローを組まずに、そのうちどれでも直接実行します。実行は、パラメーターをそのノードのエンドポイント POST /v1/<type> に送信し、待機できるジョブを返します。これは、CLI が nodaro nodes run で使うのと同じ経路で、Nodaro の MCP ツールが使う経路でもあります。REST での見方については、単体のノードを実行するを参照してください。

メソッド

client.nodes

list()

サーバーが対応するすべてのノードタイプを一覧表示します。応答は、サーバー側で 5 分間キャッシュされることがあります。この呼び出しは無料で、スコープも必要ありません。

list(): Promise<{ data: NodeDescriptor[] }>

const { data: nodes } = await client.nodes.list()

const imageGenerators = nodes.filter((n) => n.category === "ai-image")
const takesReferences = nodes.filter((n) => n.capabilities?.includes("supports-reference-image"))

各 NodeDescriptor は、次のフィールドを持ちます。

セルフホスティングの Community と Business のインストール環境にはクレジットの仕組みがないため、そのディスクリプターには creditCost が含まれません。

get(type)

1 つのノードタイプのディスクリプターを読み取ります。

get(type: string): Promise<{ data: NodeDescriptor }>

const { data: node } = await client.nodes.get("generate-video")
console.log(node.providers)  // every video model id
console.log(node.creditCost) // Nodaro Cloud only

モデルの横に料金を表示するには、node.providers を client.credits.modelCosts() に渡します。

run(type, params?, options?)

1 つのノードを開始し、すぐに応答を返します。ボディは POST /v1/<type> に送信されます。これは、すべての生成ノードが使うルートです。フィールド名は、そのノードの入力フィールドと一致します。

run(type: string, params?: Record<string, unknown>, options?: { idempotencyKey?: string }): Promise<RunNodeResult>

const result = await client.nodes.run("generate-image", {
  prompt: "A snow leopard in the mountains",
  provider: "nano-banana-2",
})

if ("jobId" in result) {
  const { data: job } = await client.jobs.getStatus(result.jobId)
  console.log(job.status)
}

返ってくるもの。ほとんどのノードタイプは非同期です。結果には jobId が含まれ、ワーカーが生成を行います。終わるまで client.jobs.getStatus(jobId) をポーリングするか、runAndWait() を使います。combine-text などの一部のインラインノードタイプは、jobId を返さずに、完全な結果をすぐに返します。jobId の有無で分岐してください。

パラメーターの補正。画像のノードタイプ（generate-image、image-to-image、edit-image）では、選んだモデルが受け付けない値を、サーバーが補正することがあります。実行は補正された値のまま進み、確保されるクレジットもそれに合わせたものになります。結果には、補正されたフィールドごとに 1 つのエントリーを持つ adjustments が含まれます。

const result = await client.nodes.run("generate-image", {
  prompt: "A snow leopard",
  provider: "gpt-image-2",
  aspectRatio: "3:2",
})
if ("adjustments" in result && result.adjustments?.length) {
  for (const a of result.adjustments) {
    console.warn(`${a.field}: ${a.from} -> ${a.to ?? "(dropped)"} (${a.reason})`)
  }
}

各補正は、field（aspectRatio、resolution、quality、duration のいずれか）、from、to、reason を持ちます。何も変わらなかった場合、adjustments は存在しません。

アカウントが支払えない場合は InsufficientCreditsError を、ストレージが満杯の場合は StorageExceededError を、デプロイ環境のコンテンツポリシーがリクエストを拒否した場合は JobBlockedError をスローします。エラーを参照してください。

runAndWait(type, params?, opts?)

1 つの非同期ノードを、完了まで実行します。内部で run() を呼び出し、jobId を受け取って、ジョブが終わるまで client.jobs.getStatus() をポーリングします。ステータスが completed になると、ジョブの出力で解決されます。

runAndWait(type: string, params?: Record<string, unknown>, opts?: RunAndWaitOptions): Promise<NodeJobOutput>

const output = await client.nodes.runAndWait(
  "generate-video",
  { prompt: "Rain falls on a neon street at night", provider: "seedance-2-fast", duration: 4 },
  { onProgress: (s) => console.log(`${s.progress ?? 0}%`) },
)
console.log(output.videoUrl, output.thumbnailUrl)

出力は NodeJobOutput です。画像ノードでは imageUrl、動画ノードでは videoUrl と thumbnailUrl、オーディオノードでは audioUrl、それ以外にもノードが書き込むフィールドがあります。たとえば、音源分離（Audio Separation）は、ステムごとに 1 つの URL を追加します。vocalUrl や instrumentalUrl などです。

次の型付きエラーをスローします。

復旧に時間がかかる場合。モデルが、ワーカーがあきらめた後に結果を返すことがあります。その場合、プラットフォームが復旧している間、ジョブは recovering: true のまま processing にとどまります。遅いモデルでは、数十分かかることがあります。JobTimeoutError で待機が終わった場合は、後で client.jobs.get(jobId) を使ってジョブを取得するか、maxMs を上げてください。

runMany(type, paramsList, opts?)

1 つのノードタイプで複数の実行を同時に開始し、すべてを待機します。たとえば、候補のグリッドを生成する場合です。各エントリーは runAndWait() を通して実行されます。

runMany(type: string, paramsList: Record<string, unknown>[], opts?: RunAndWaitOptions): Promise<RunManyResult[]>

const results = await client.nodes.runMany("generate-image", [
  { prompt: "A snow leopard at sunrise" },
  { prompt: "A snow leopard at golden hour" },
  { prompt: "A snow leopard at blue hour" },
])
for (const { jobId, output } of results) console.log(jobId, output.imageUrl)

すべての実行が終わると解決され、入力順に、エントリーごとの { jobId, output } が返されます。いずれかの実行が失敗すると、runAndWait() と同じエラーで、すぐに拒否されます。その後にいちばんよい結果を選ぶには、URL を client.reduce.run() に渡します。

型付きパラメーター

4 つのノードタイプには型付きのパラメーターがあり、コードエディターがそのフィールドを補完し、チェックします。それ以外のノードタイプは、すべて素のオブジェクトを受け取ります。そのフィールドは、そのノードの入力フィールドで、inputSchema と、ノードリファレンスのそのノードのページに一覧表示されています。3D シーンのノードにも型付きのパラメーターがあります。3D シーンを参照してください。

型付きのパラメーターのオブジェクトは、そのルートのほかのフィールドも受け付けます。サーバーは、ボディ全体を検証します。

GenerateImageParams

GenerateVideoParams

画像から動画を作る経路です。開始フレーム、任意の終了フレーム、リファレンスを使います。

TextToVideoParams

プロンプトだけで動画を作る経路で、POST /v1/text-to-video です。プロンプトは必須で、開始フレームと終了フレームは代わりに generate-video が扱います。text-to-video のモードがないモデルは、400 image_required を返します。

AssembleNarratedVideoParams

動画のブロックをナレーションとつなぎ合わせて、1 本の動画にします。実行の料金は 3 + ceil(blocks / 6) クレジットです。各ブロックをナレーションに合わせる方法については、ナレーション付き動画を合成を参照してください。

リファレンス

generate-image、generate-video、text-to-video は、エディターが接続するのと同じ形でリファレンスを受け付けます。サーバーは、それらをプロンプト内で @image_1 のような番号付きの指示に変換するので、自分で「Image 1 is...」のように書く必要はありません。

• connectedReferences は、ConnectedReference エントリーのリストで、エディターの接続されたリファレンスと同じ形をしており、SDK からエクスポートされています。サーバーは重複を取り除き、そのモデルが受け付ける数だけ残します。referenceOrder は、ID によってその順序を決めます。
• 顔の固定。エントリーは identityLock: { enabled: true, text? } を持てます。この場合、サーバーは、そのリファレンスのアイデンティティを保つようモデルに伝える短い一文を追加します。text は組み込みの言い回しを置き換え、その中の {ref} はリファレンスの名前を表します。デフォルトではオフです。
• describedReferences は、名前は分かるが画像がない被写体のために、最大 10 個の { name, description } エントリーを受け付けます。台本の役どころなどです。それぞれが、プロンプト内で Name — description. という行になります。モデルがその人物だと分かるように、プロンプトの文章にも名前を残してください。
• リファレンスのエントリーの descriptionOverride は、この実行に限って、保存されている説明を置き換えます。
• 動画とオーディオのリファレンスのキャプション。referenceVideoCaptions と referenceAudioCaptions は、referenceVideoUrls と referenceAudioUrls の順序に従います。各キャプションは、プロンプト内で @video_1: caption. または @audio_1: caption. のように表示されます。
• プロンプト内で画像のリファレンスをメンションする。generate-image では、リファレンスに名前を付けて、@<name>:<index> または @<name>:<index>:<role> として（たとえば @town:1:background）メンションできます。メンションすると、プロンプトのその位置に、そのリファレンスまたはその役割が反映されます。~lock と ~nolock は、キャラクターのメンションと同じように使えます。

使える役割についてはリファレンスの役割を、アイデンティティの扱いについてはキャラクターの一貫性を参照してください。

演出

generate-image、generate-video、text-to-video は、言葉の代わりに、ピッカー ID による direction オブジェクトを受け付けます。Nodaro が各 ID に対応する検証済みの言い回しをプロンプトに書き込むので、コードは ID を送るだけで、言い回しは常に最新の状態に保たれます。

await client.nodes.runAndWait("generate-image", {
  prompt: "A detective waits under a street lamp",
  direction: { shotSize: "wide-shot", timeOfDay: "golden-hour", mood: "suspicious" },
})

• キーは、shotSize、lightingStyle、style、mood、photographer、era などのピッカーの次元です。動画のルートでは、cameraMotion、actionFx、transition、loopSubject、temporal の各キーなど、動きに関するキーが加わります。
• 値は、1 つの ID か、ID の配列です。複数の値を取れる次元では、それぞれの上限までを残し、残りは取り除かれます。リクエストが拒否されるのは、1 つのキーにつき 8 個を超える値、または 1 つの ID につき 100 文字を超える場合だけです。
• 不明なキーと ID は、拒否されずに読み飛ばされます。空の direction は、プロンプトを変更しません。
• 1 つのマップが、画像と動画の両方に対応します。静止画専用のキーを動画の実行に送っても、受け付けられ、何も追加されません。
• extend-video は direction を受け付けません。そのプロンプトは、既存のクリップの続きだからです。

有効な ID は、client.pickerCatalogs から取得します。すべての次元については、ピッカーカタログを参照してください。

言語モデルのノード

run(type, params) は /v1/<type> に送信します。言語モデルのノードでこのルートが存在するのは、generate-script、image-critic、qa-check、describe-to-picker だけです。それ以外の言語モデルのノードは、より長いパスを使うため、client.request() で呼び出します。

await client.nodes.run("generate-script", {
  prompt: "A 3-scene product launch script for a smart water bottle",
  reasoningEffort: "high",
})

• reasoningEffort は、モデルによって "none"、"low"、"medium"、"high"、"xhigh"、"max" のいずれかです。省略するか、そのモデルが対応していない段階を送信すると、モデルのデフォルトになります。xhigh と max は、クレジットのティアが 1 段階上がります。モデルとそのティアについては、プロンプト（Prompt）を参照してください。
• advancedMode: true は、Gemini モデルを、その開発元の API 上で直接実行します。temperature、maxTokens、推論の全範囲が完全に有効になるのは、そこだけです。reasoningEffort による上昇分に加えて、クレジットのティアが 1 段階上がります。このオプションがないモデルは、400 advanced_mode_unsupported を返します。
• ストリーミングはラップされていません。SDK は、プロンプトノードのストリーミングの応答を読み取りません。読み取り可能なストリームを使う fetch を使ってください。

モデル固有のルール

一部の動画モデルは、ほかのモデルにはない値を受け付けます。各モデルのページに、すべての選択肢と料金が一覧表示されています。

• Seedance 2 は、resolution: "4k" と、aspectRatio: "adaptive" または "21:9" を受け付けます。Seedance 2 Fast と Seedance 2 Mini は、480p または 720p でのみレンダリングします。
• Seedance 2.5 は、480p、720p、1080p でレンダリングし、1 回の呼び出しで最大 30 秒を作れ、画像 30 個、動画 10 個、オーディオ 10 個のリファレンスを受け付けます。開始フレームがある場合、そのフレームのアスペクト比を使い、明示的な aspectRatio は拒否します。
• MiniMax Hailuo 3（minimax-h3）は、画像 9 個、動画 3 個、オーディオ 3 個のリファレンスを、resolution: "2K"（デフォルト）または "768P" で受け付けます。それ以外の値は、2K としてレンダリングされ、課金されます。
• Wan 3.0（wan-3 と、より高速な wan-3-prime）は、画像 10 個、動画 5 個、オーディオ 5 個のリファレンスを受け付けます。リファレンスのリストは、imageUrl や endFrameUrl と組み合わせられません。duration は 2〜30 の整数で、resolution は 480p、720p、1080p のいずれかです。
• Gemini Omni Flash は、Gemini Omni と同じリクエストを受け付けます。長さは 4、6、8、10 秒のいずれか、解像度は 720p〜4K、フレームは 16:9 または 9:16 のみです。

テキストから音声。provider を省略すると、テキストから音声（Text to Speech）は、3,000 文字までのテキストに ElevenLabs v3 を使います。それより長いテキストは、上限が 40,000 文字の ElevenLabs Turbo v2.5 にフォールバックするため、途中で切れることはありません。自分で指定した provider は、常にそのまま使われます。

スクレイパーとその他の入力ノード

入力ノードも、同じように実行します。Web スクレイピング（Web Scrape）などのスクレイパーは、すぐに応答します。結果には、履歴のための jobId と、データ自体の両方が含まれるため、ポーリングせずに使えます。リクエストのフィールドは、そのノードの入力フィールドで、inputSchema に一覧表示されています。