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

ノードの実行

ワークフローを組まずに、TypeScript から Nodaro のノードを実行します。ノードタイプの検出、実行の開始と待機、リファレンスやカメラの演出の指定までを扱います。

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

メソッド

メソッド内容
nodes.list()すべてのノードタイプを、モデルとクレジットの料金とともに一覧表示します
nodes.get(type)1 つのノードタイプを読み取ります
nodes.run(type, params?, options?)ノードを開始し、すぐにジョブ ID を返します
nodes.quote(type, params?)実行を開始する前に料金を見積もります
nodes.runAndWait(type, params?, opts?)ノードを開始し、そのジョブをポーリングして、出力を返します
nodes.runMany(type, paramsList, opts?)1 つのノードで複数の実行を同時に開始し、すべてを待機します
nodes.runBatchAndWait(type, params, opts?)1 回の画像生成の呼び出しで複数の画像を作成し、すべてを待機します

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 は、次のフィールドを持ちます。

フィールド型説明
typestringAPI のタイプです。generate-image などです。run() に渡します。
labelstringエディターでのノードの名前です。
categorystringカテゴリーです。ai-image、ai-video、ai-audio、ai-text、processing、parameter などです。
descriptionstring1 行の説明です。
outputTypestringtext、image、video、audio、data、none のいずれかです。
creditCostnumber | string実行に請求されるクレジットの料金で、ノードの実行ボタンと同じ数値です。固定の場合は数値、モデルによって異なる場合は "3-682" のような範囲です。動画のトリミング、動画をループ、動画を結合では、代わりに 5 秒の 1 段階分の料金で、実行の料金はこれに段階の数を掛けた額です。Nodaro Cloud のみです。
estimatebooleancreditCost が見積もりの場合は true です。見積もりは、従量課金の LLM ノードのデフォルトのモデルでの一般的な呼び出しの料金です。≈N と表示してください。デフォルトのモデルにまだ料金のない従量課金の LLM ノードは、creditCost: "unpriced" を返します。
creditRateNodeCreditRate話者フレーム(creditCost は "per-1000-frames")のように、ノード独自の単位ごとに課金されるノードで使います。{ identifier, unit, creditsPerUnit, minUnits, rounding, note } です。N 単位の実行には Math.ceil(Math.max(minUnits, N) * creditsPerUnit) が課金され、丸めは 1 回だけです。
providersstring[]ノードが実行できるモデル ID で、provider パラメーターに使います。
capabilitiesstring[]supports-reference-image や supports-end-frame などのフラグです。
inputSchema{ fields }設定できる入力フィールドで、それぞれ key、type、required、options を持ちます。
maxDurationSecnumberノードが受け付ける最長の長さです。長さの制限があるノードにだけ存在します。
providerResolutionsRecord<string, string[]>各モデルが受け付ける解像度で、モデルによって異なる場合に存在します。

セルフホスティングの 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)
}

専用のルートを持つノードタイプ。 一部のノードタイプは別のルートで実行され、run() はそのルートに自動で送信します。

ノードタイプルート
generate-3d-scene、edit-3d-scene/v1/3d-scene/generate、/v1/3d-scene/edit
llm-chat、after-effects、motion-graphics、lottie-overlay、3d-title/v1/<type>/generate
image-to-text/v1/image-to-text/describe
video-composer/v1/scene-graph/generate
telegram-channel-feed/v1/telegram-channel/fetch
Suno スピーチを除く、suno-generate や suno-cover など、すべての suno-* ノード/v1/suno/<name> です。suno-voice は /v1/suno/voice/generate を使います。suno-speech は既定のルート、/v1/suno-speech を使います。
instagram-post、tiktok-post、youtube-upload、linkedin-post、x-post、facebook-post、telegram-post、publish-social/v1/social/publish
ugc-creator、ugc-script、ugc-clips、ugc-clip、ugc-cards/v1/ugc/creator、/v1/ugc/script などです。Nodaro Cloud のみです。
planType を指定した render-video/v1/render-video/plan

公開のルートには platform が必要です。x-post など、1 つのプラットフォーム用のソーシャルノードは、省略した場合、そのタイプから platform を補います。publish-social は、送信した platform を使います。

単独では実行できないノードタイプ。 専用のルートを持たないノードタイプは、API を呼び出さずに、code が node_not_runnable の NodaroError で拒否されます。そのメッセージに、代わりに実行するものが示されます。

  • modify-image は image-to-image で実行します。nano-banana-edit モデルの場合は edit-image で実行します。
  • upscale-image と remove-background は edit-image で実行します。
  • image-to-video は generate-video で実行します。
  • composite、manual-edit、paint-mask は、ワークフローの中でだけ実行されます。scene と generative-pipeline は、パイプラインの中でだけ実行されます。

入力、トリガー、ユーティリティ、ピッカー(upload-image、combine-text)など、ワークフローの中でだけ実行されるノードタイプは、それらのルートがないと API が応答した時点で、同じように拒否されます。存在しないキャラクター ID など、見つからないリソースについての 404 は、NotFoundError のままです。

このデプロイ環境が提供していないモデルや、管理者がオフにしたモデルは、クレジットが確保される前に拒否されます。呼び出しは、code が model_not_available または model_disabled の ModelUnavailableError で拒否されます。別のモデルを選んでください。再試行しても結果は変わりません。

返ってくるもの。ほとんどのノードタイプは非同期です。結果には jobId が含まれ、ワーカーが生成を行います。終わるまで client.jobs.getStatus(jobId) をポーリングするか、runAndWait() を使います。meta-ads-scrape などの一部の同期ノードタイプは、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 をスローします。エラーを参照してください。

quote(type, params?)

POST /v1/quote で、実行を開始する前に料金を見積もります。run に渡すのとまったく同じボディを渡してください。プラットフォームは、実行のルート自体のコードで料金を計算します。検証、リファレンスのクリップの測定、クレジット ID、金額はすべて同じです。何も開始されず、課金もされません。Nodaro Cloud のみです。

quote(type: string, params?: Record<string, unknown>): Promise<NodeQuote>

このメソッドは、text-to-video、generate-video、video-to-video、video-upscale(Seedance 2.5 のドラフトの 1080p 仕上げは、ドラフトから料金が計算されます)、edit-image に型付けされています。ai-avatar、cinematic-avatar、switchx は、実行のボディをそのまま受け付けます。split-into-layers も見積もれ、client.media.splitIntoLayers と同じボディを受け付けます。これらが、現在プラットフォームが見積もれるタイプです。ほかのタイプは 400 quote_unsupported で拒否されます。実行が拒否するボディ、モデル、ノードは、実行自体の 400 または 403 で拒否されます。

const q = await client.nodes.quote("video-to-video", {
  videoUrl, prompt: "make it black and white", provider: "seedance-2-5", resolution: "480p",
})
q.reserve   // credits held when the run starts
q.expected  // what the run should actually cost, when known

settles_to_actual の警告は、reserve が実行にかかりうる最大額であることを示します。実行は届けた分で課金され、残りは返還されます。警告がない場合、reserve は実行が完了したときに課金される額です。

// Nodaro Image Upscale: the exact price of this picture at this factor.
// The platform reads the picture to measure it, and stores nothing.
const up = await client.nodes.quote("edit-image", {
  provider: "nodaro-image-upscale", imageUrl: "https://example.com/photo-1024.png", upscaleFactor: "2",
})
up.identifier // "nodaro-image-upscale:2K" for a 1024 × 1024 picture

// Split into Layers: the hold, the most the run can cost (warning settles_to_actual).
const split = await client.nodes.quote("split-into-layers", { imageUrl: "https://example.com/poster.png", maxLayers: 5 })
split.identifier // "split-into-layers:1k:6": 5 layers and the base at 1K

Nodaro Image Upscale が提供されていない場合、見積もりは画像を読み取る前に、実行と同じ 403 model_not_available(ModelUnavailableError)で拒否されます。ほかのサイトへのリンクは、デプロイメントのリンク取り込みの設定に従います。

NodeQuote は { identifier, reserve, expected?, adjustments, warnings } です。すべてのフィールドとコードについては、実行の見積もりを参照してください。

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 に画像のピクセルサイズも入るので、クライアントは画像が読み込まれる前にグリッドをレイアウトできます。

フィールド型説明
imageUrlstring画像です。ジョブが複数の画像を作成した場合は、最初の 1 枚です。
imageUrlsreadonly string[]ジョブが 2 枚以上の画像を作成した場合の、すべての画像です。
width、heightnumber保存されている imageUrl のピクセルサイズで、EXIF の向きが適用されています。無料プランの透かしも含まれます。
imagesreadonly JobOutputImage[]imageUrls の各エントリーに対応する { url, width?, height? } で、同じ順序です。サイズのないエントリーは、測定できなかったものです。

4 つのサイズのフィールドは省略可能です。古いジョブにはなく、サーバーは読み取れなかったサイズを推測で入れることはありません。

const output = await client.nodes.runAndWait("generate-image", { prompt: "a snow leopard in the mountains" })
console.log(output.imageUrl, output.width, output.height)
for (const image of output.images ?? []) console.log(image.url, image.width ?? "?", image.height ?? "?")

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

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

エラー発生する場合
コード batch_requires_run_batch_and_wait の NodaroErrorcount が 1 より大きい、または models を指定した generate-image のリクエストは、複数のジョブを作成します。runAndWait() は、何も送信する前にこれを拒否します。runBatchAndWait() を使ってください。
InsufficientCreditsError、StorageExceededError、JobBlockedErrorポーリングが始まる前に、実行のリクエストが拒否された場合です。
ModelUnavailableErrorこのデプロイ環境がモデルを提供していないか、管理者がモデルをオフにした場合です。実行は、クレジットが確保される前に拒否されます。別のモデルを選んでください。
JobFailedErrorジョブが failed または cancelled で終わった場合です。jobId とジョブのエラーメッセージを持ちます。
JobTimeoutErrormaxMs が経過した場合です。ジョブはキャンセルされません。
JobAbortedError自分の signal が発火した場合です。ジョブはキャンセルされません。
JobHeldErrorコンテンツポリシーのあるデプロイ環境で、ジョブが人によるレビューのために保留されている場合です。

復旧に時間がかかる場合。モデルが、ワーカーがあきらめた後に結果を返すことがあります。その場合、プラットフォームが復旧している間、ジョブは 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() と同じエラーで、すぐに拒否されます。count が 1 より大きい、または models を指定した、それ自体がバッチであるエントリーは、何も送信する前に拒否されます。その後にいちばんよい結果を選ぶには、URL を client.reduce.run() に渡します。

runBatchAndWait(type, params, opts?)

1 回の画像生成の呼び出しで複数の画像を作成し、すべてを待機します。count では、1〜4 枚の画像を、それぞれ別のジョブとして作成します。models では、1 つの provider の代わりに、2〜4 個の画像モデルに同じリクエストを送ります。両方を指定すると、count はモデルごとに適用され、合計で最大 8 枚の画像になります。

runBatchAndWait(
  type: "generate-image",
  params: GenerateImageParams,
  opts?: RunAndWaitOptions,
): Promise<GenerateImageBatchOutput>

このメソッドはバッチを一度送信し、そのあと runAndWait() と同じ方法ですべてのジョブを待機します。バッチは全体として残高と照合され、全体として課金されるか、まったく課金されないかのどちらかです。opts.idempotencyKey を指定すると、i 番目の画像のキーは <key>:<i> になるので、再試行しても同じジョブが返され、再び課金されることはありません。presetId は、どちらの方法とも組み合わせられます。プリセットのリクエストで count 枚の画像を作成するか、モデルごとにプリセットを 1 回ずつ適用します。

const { batch, results } = await client.nodes.runBatchAndWait(
  "generate-image",
  { prompt: "a lighthouse at dusk", models: ["gpt-image-2", "flux-2-max"], count: 2, seed: 41 },
  { idempotencyKey: crypto.randomUUID() },
)
console.log(batch.batchId, batch.totalCredits)
for (const r of results) {
  if (r.status === "completed") console.log(r.model, r.output.imageUrl)
  else console.warn(r.model, r.jobId, r.error.message)
}

{ batch, results } で解決されます。

  • batch は送信に対する応答で、GenerateImageBatchResult です。jobId(最初のジョブ)、jobIds(モデルごと、その中で画像ごとの順)、batchId、groups(モデルごとの { model, jobIds, credits?, adjustments? })、totalCredits を持ちます。パラメーターで count を 1 より大きくするか models を指定した場合、nodes.run("generate-image", …) も同じオブジェクトを返します。
  • results は、ジョブごとに 1 つの BatchJobOutcome を、batch.jobIds の順に持ちます。それぞれ { jobId, model, status: "completed", output } または { jobId, model, status: "error", error } です。error は、待機を終わらせた JobFailedError、JobHeldError、JobTimeoutError のいずれかです。1 枚の画像が失敗しても、ほかの画像が破棄されることはありません。

拒否されるのは、ジョブが 1 つも存在しない段階で、送信自体のエラーが起きた場合だけです。たとえば、バッチの合計を required に持つ InsufficientCreditsError です。自分の signal が発火した場合も、JobAbortedError で拒否されます。画像 1 枚のリクエストは、何も送信する前にコード not_a_batch で拒否されます。その場合は runAndWait() で待機してください。seed を指定すると、i 番目の画像は seed + i を使います。あとでバッチのジョブを探すには、client.jobs.list({ batchId }) を使います。

型付きパラメーター

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

ノードタイプパラメーターの型ノードのページ
generate-imageGenerateImageParams画像生成
image-to-imageImageToImageParams画像修正
edit-imageEditImageParams画像をアップスケール
split-imageSplitImageParams
generate-maskGenerateMaskParamsマスク生成
generate-videoGenerateVideoParams動画生成
text-to-videoTextToVideoParams動画生成
video-to-videoVideoToVideoParams動画から動画
assemble-narrated-videoAssembleNarratedVideoParamsナレーション付き動画を合成
video-depthVideoDepthParams動画の深度
video-upscaleVideoUpscaleParams動画をアップスケール

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

GenerateImageParams

プロパティ

型

strength と guidanceScale も、GenerateImageParams に型付けされています。

画像のファイル形式

GenerateImageParams と ImageToImageParams には outputFormat(ImageOutputFormat)が型付けされています。既定は "png" で、client.models.list() の outputFormats にあるモデルでは "jpeg"、"webp"、"gif"、"svg" も指定できます。現在、対象は GPT Image 2.6 Flare と Sunburst です。

  • GIF は gifFrames(2〜16)と gifFrameDurationMs(20〜2,000 ミリ秒、10 刻み)を受け付けます。GIF は正方形で、1 フレームあたり 512×512 です。aspectRatio と resolution は無視され、そのことが adjustments に示されます。
  • SVG は svgLevel(ImageSvgLevel)を受け付けます:"standard"、"detailed"、"max"。
  • 透明な背景が保たれるのは、PNG と WebP だけです。
  • GIF や SVG ではマスクを使えません。リクエストは 400 で拒否されます。

完了したジョブの出力では、imageMimeType にファイルの種類が入ります。GIF や SVG の場合は、thumbnailUrl に PNG の静止画も入ります。GIF の料金は、品質と、フレーム数が入る区分(2〜8、9〜12、13〜16)で決まります。画像生成ノードは、実行前に料金を表示します。

await client.nodes.runAndWait("generate-image", {
  prompt: "a waving flag",
  provider: "gpt-image-2-6-flare",
  outputFormat: "gif",
  gifFrames: 12,
} satisfies GenerateImageParams)

画像生成でのプリセット

presetId は、エディターとまったく同じようにノードプリセットを適用します。プロンプト、前後のテキスト、プレースホルダーのデフォルト、スタイル、ネガティブプロンプト、設定です。これで、ジョブはエディターの実行と一致します。presets.listFactory("generate-image") の標準プリセットの ID か、自分のプリセットの ID を使ってください。指定したフィールドは、プリセットより優先されます。

デフォルトのないプレースホルダーには、presetVariables で値を指定する必要があります。指定しないと、呼び出しは 400 preset_variables_required で失敗し、そのプレースホルダーの名前が示されます。

await client.nodes.runAndWait("generate-image", {
  presetId: "generate-image/logo-wordmark",
  presetVariables: { BRAND: "Acme" },
})

GenerateVideoParams

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

プロパティ

型

TextToVideoParams

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

プロパティ

型

TextToVideoParams は contentPolicyRewrite?: boolean を受け取ります。指定しないか true の場合、著作権による拒否は、言い換えたプロンプトで 1 回だけ再試行されます。false の場合、著作権による拒否でジョブは失敗します。

Seedance 2.5 のリファレンスのタスクタイプ

GenerateVideoParams と TextToVideoParams は、referenceTaskType?: "auto" | "reference" | "edit" | "extend" を受け付けます。これは、リファレンスメディアの用途を、プロンプトに任せずに seedance-2-5 に伝えます。ほかのモデルはこれを無視し、リファレンスメディアのない実行も無視します。開始フレームや終了フレームは、リファレンスメディアに数えられません。

  • "auto" はデフォルトで、何も宣言しません。
  • "reference" は、aspectRatio と duration をそのまま保ちます。長さが自動(-1)の場合、実行はモデルが作れる最長の出力で確保され、作った分が課金されます。
  • "edit" は、リファレンス動画を、動画自身の形と長さで編集します。aspectRatio は "adaptive"、duration は自動になります。すべてのリファレンス動画が 4〜30 秒である必要があります。そうでない場合は何も宣言されず、送った比率と長さのままです。
  • "extend" は、リファレンス動画の続きを、動画自身の形で、決まった長さで作ります。自動の duration や duration がない場合は、モデルのデフォルトの長さになります。返されるのは続きだけで、元の動画とはつながりません。両方を 1 本にするには、extend-video を実行してください。
  • edit と extend にはリファレンス動画が必要です。ドラフト(draft: true)は、draft なしの同じ実行とまったく同じようにタイプを宣言し、480p で作られます。

変更した内容は result.adjustments で返され、nodes.quote は実行と同じ方法でボディの料金を計算します。Seedance 2.5 のリファレンスのタスクタイプを参照してください。

await client.nodes.run("generate-video", {
  provider: "seedance-2-5",
  prompt: "remove the sign on the wall",
  referenceVideoUrls: [clipUrl],
  referenceTaskType: "edit",
} satisfies GenerateVideoParams)

Seedance 2.5 のドラフト

GenerateVideoParams と TextToVideoParams は draft: true を受け付けます。seedance-2-5 では、実行は 480p の実行と同じ料金の 480p ドラフトになります。気に入ったテイクは、run("video-upscale", { provider: "seedance-2-5-hd", sourceJobId }) で仕上げます。同じテイクを 1080p で再レンダリングするもので、料金はドラフトの長さから決まります。自分の完了したドラフトでないソースは、何かが請求される前に 4xx で拒否されます。Seedance 2.5 のドラフトモードを参照してください。

const draft = await client.nodes.run("generate-video", { prompt, provider: "seedance-2-5", draft: true, duration: 8 })
// Wait for the draft and review it. When you like the take, finalize it at 1080p.
if ("jobId" in draft) {
  const final = await client.nodes.runAndWait("video-upscale", { provider: "seedance-2-5-hd", sourceJobId: draft.jobId })
  console.log(final.videoUrl)
}

Topaz での動画のアップスケール:VideoUpscaleParams は、targetResolution("720p"、"1080p"、"4k" のいずれかで、フレームの短辺。デフォルトは 1080p)と targetFps(15〜60。デフォルトはソース自体のフレームレート)を受け付けます:run("video-upscale", { videoUrl, targetResolution: "4k", targetFps: 60 })。Topaz は従量課金です。動画をアップスケール › クレジットを参照してください。upscaleFactor は非推奨です。引き続き受け付けられ、ソースの短辺に適用されます。

Nodaro Video Upscale:provider: "nodaro-video-upscale" は、出力フレームとして targetResolution の "1080p"(デフォルト)、"2k"、"4k" を受け付けます。"720p" など、受け付けない値は 1080p で実行されます:run("video-upscale", { provider: "nodaro-video-upscale", videoUrl, targetResolution: "2k" })。

  • 60 秒以内かつ 50 MB 以内のクリップを受け付けます。クリップの秒単位で料金が決まり、確保される額がそのまま課金されます。
  • 提供されるのは、models.list に含まれる場合だけです。それ以外では、リクエストは 403 model_not_available(ForbiddenError)で拒否されます。
  • ほかの拒否:上限を超えたクリップや読み取れないクリップには 400(video_too_long、video_too_large、video_unreadable)、デプロイメントがほかのサイトへのリンクをオフにしている場合のそのリンクには 403 link_imports_disabled が返されます。
  • デプロイメントのアップロードポリシーが拒否するクリップには 422 upload_blocked が返されます。今すぐ取得できなかったクリップには 429 input_busy、または 503 input_timed_out か input_failed が返されます。同じリクエストをもう一度送ってください。
  • どの拒否も、課金の前に行われます。"2k" はこのプロバイダー専用の値で、Topaz と VEO では引き続き 400 になります。

VideoToVideoParams

動画編集の経路である POST /v1/video-to-video です。seedance-2-5 の編集はサーバー上で組み立てられるため、ほかの編集モデルと同じボディを送信します。動画から動画を参照してください。

プロパティ

型

この型には、audio、multiShots、videoEditDuration、audioSetting、promptExtend も含まれ、それぞれを受け付けるモデルで使います。sessionId と origin も含まれます。ほかのモデルは、3 つのリファレンスのリストを拒否します。リファレンスの番号付けと上限については、動画から動画を参照してください。

型付きの画像ルート

image-to-image、edit-image、split-image、generate-mask には、run に型付きのオーバーロードがあります。ジョブを開始する 3 つには、runAndWait にもあります。各パラメーターの型は、ModifyImageProvider、ImageEditProvider、ImageAspectRatio、ImageResolution など、プラットフォーム自体の語彙を受け付け、SDK はこれらを再エクスポートします。ルートのほかのフィールドも、そのまま渡されます。

コンパイル時のチェックが適用されるのは、ボディがパラメーターの型として型付けされている場合です。const params: EditImageParams = …、またはインラインの { … } satisfies EditImageParams です。型付きのオーバーロードが拒否するボディを呼び出しに直接書いた場合は、それでもコンパイルされます。型なしの run(type: string, …) のオーバーロードに渡され、ルートが 400 を返します。チェックを受けるには satisfies を使ってください。

  • image-to-image、edit-image、generate-mask。 run は ImageJobStarted、つまり { jobId: string; adjustments? } を返すため、result.jobId にキャストは不要です。
  • ImageToImageParams では、imageUrl と prompt が必須です。その maskUrl(白い部分が変更する領域)は、モデル自体のマスクとして送られます。これを使うのは ideogram-edit、flux-fill、gpt-image-2-6-flare-i2i、gpt-image-2-6-sunburst-i2i だけです。GPT Image 2.6 では、画像のそれ以外の部分は元のまま正確に保たれ、結果は元の画像のサイズになります。実行は写真の形を保ち、写真に最も近いサイズでレンダリングされ、課金されます。そのことは adjustments に示されます。マスクに追加料金はかかりません。GenerateImageParams と同じく、outputFormat と GIF・SVG のフィールドも受け付けます。
  • EditImageParams は、2 つの形のいずれかです。Grok のタスク操作以外のすべてのモデルでは、imageUrl を受け付けます。Grok のタスク操作では、provider: "grok-2-edit" | "grok-2-segment" とともに taskId を受け付けます。これは以前の Grok Imagine 2 の生成のタスク ID で、そのジョブの出力データに保存されています。両方を送る型付きのボディや、別のモデルでの taskId は、コンパイルされません。モデルのデフォルトは recraft-upscale です。nano-banana-edit と grok-2-edit では prompt が必須です。maskIndexes は grok-2-edit 専用です。
  • upscaleFactor(UpscaleFactor:"1"、"2"、"4"、"8")は、topaz-image-upscale では 1、2、4、nodaro-image-upscale では 1、2、4、8 です。モデルが受け付けない倍率は 400 validation_error です。nodaro-image-upscale は、出力のサイズで料金が決まります。67,108,864 ピクセルを超える出力や、1 辺が 16,384 ピクセルを超える出力は、課金の前に 400 image_too_large で拒否されます。Nodaro Image Upscaleを参照してください。
  • split-image は無料で、すぐに応答します。ジョブを作成しないため、runAndWait は使えません。run は SplitImageResult、つまり { images: { name, url }[] } を返し、names の順にタイルごとに 1 枚の PNG を含みます。names には、ちょうど gridCols × gridRows 個の項目が必要で、gridCols と gridRows はそれぞれ 1〜6 です。
  • generate-mask は、SDK で マスク生成のジョブを開始する方法です。runAndWait("generate-mask", …) は GenerateMaskJobOutput を返します。被写体が白になるマスクの PNG である maskUrl と、そのまま渡された元の画像である imageUrl です。
import type { EditImageParams, GenerateImageParams, GenerateMaskParams } from "@nodaro/sdk"

const { maskUrl } = await client.nodes.runAndWait("generate-mask", { imageUrl, prompt: "the red car" } satisfies GenerateMaskParams)
await client.nodes.runAndWait("generate-image", { prompt: "a blue car", baseImageUrl: imageUrl, maskUrl } satisfies GenerateImageParams)
const { jobId } = await client.nodes.run("edit-image", { imageUrl, provider: "topaz-image-upscale", upscaleFactor: "4" } satisfies EditImageParams)
await client.nodes.runAndWait("edit-image", { imageUrl, provider: "nodaro-image-upscale", upscaleFactor: "8" } satisfies EditImageParams)

VideoDepthParams

クリップを深度動画に変換します。近いものが明るく、遠いものが暗くなります(POST /v1/video-depth)。完了したジョブには videoUrl と thumbnailUrl が含まれます。料金と長さの上限は、動画の深度を参照してください。

プロパティ

型

選んだプロバイダーが受け付けない設定は無視されるため、プロバイダーを切り替えてもリクエストが失敗することはありません。上のリストにない値は 400 validation_error になります。クリップの長さは、クレジットが確保される前に測定されます。長すぎるクリップには 400 video_too_long が返されます。video-depth-anything では 2,400 フレームまたは 300 秒を超える場合、depth-anything-frames では 80 秒を超える場合です。読み取れないクリップには 400 video_unreadable が返されます。

const { videoUrl } = await client.nodes.runAndWait("video-depth", {
  videoUrl: "https://cdn.example.com/clip.mp4",
  colormap: "turbo",
  resolution: "720p",
})

AssembleNarratedVideoParams

動画のブロックをナレーションとつなぎ合わせて、1 本の動画にします。実行の料金はブロック数によって決まり、44〜143 クレジットです。これは 3 単位に、6 ブロックごとに 1 単位(6 ブロック未満の端数も 1 単位)を加えた分です。各ブロックをナレーションに合わせる方法については、ナレーション付き動画を合成を参照してください。

プロパティ

型

リファレンス

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

  • 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 を受け付けません。そのプロンプトは、既存のクリップの続きだからです。
  • 自分のパレットとムードボードは、generate-image で使えます。colorLook を paletteDirectionId(id) に、または style を moodboardDirectionId(id) に設定します。パレットとムードボードを参照してください。

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

被写体

GenerateImageParams と TextToVideoParams には、エクスポートされた Subject 型の任意の subject があります。これはショットに誰が映るか、つまり人物、そのスタイリング、フレーム内の小道具を、ピッカーのフィールドからカタログ ID へのフラットなマップで指定します。そのためのプロンプトのテキストを書く必要はありません。言い回しは Nodaro が書き、prompt のすぐ後、direction より前に置きます。

import type { Subject } from "@nodaro/sdk"

const subject: Subject = { type: "woman", age: "age-30s", hairBase: "base-short-straight", heldProp: "smartphone" }
await client.nodes.run("generate-image", { prompt: "on the seawall at dusk", subject })
  • フィールド名と ID は、ピッカーカタログから取得します。client.pickerCatalogs.get("person") と get("styling") は、各次元の field と、その options[].id を一覧表示します。get("held-prop")、get("material")、get("animal") は、カタログの valueField(heldProp、material、animal)に ID を書き込みます。
  • 値は、1 つの ID か ID のリストです。次元自体の上限を超える ID は、拒否されずに捨てられます。customAge は唯一の数値で、年齢を表し、age: "age-custom" の場合にだけ読み取られます。
  • 上限。 プリセットがない場合、ルートがマップを確認します。キーが 128 個を超える、キーが 64 文字を超える、1 つのキーの ID が 8 個を超える、または ID が 100 文字を超える場合は、400 validation_error になります。これらの上限内の不明なキーや ID は飛ばされ、ジョブの input_data.subject には、実際に使われた ID だけがそのまま残ります。
  • presetId がある場合、direction と同じく、あなたの subject がプリセット自体のものに置き換わり、プリセットのプロンプトに追加されます。長すぎる値は拒否されずに捨てられ、input_data には被写体が記録されません。

すべてのキーと、言い回しが追加される順番については、ノードを参照してください。

言語モデルのノード

run(type, params) は、言語モデルの各ノードタイプを、それぞれ専用のルートに送信します。generate-script、image-critic、qa-check、describe-to-picker は /v1/<type>、それ以外はより長いパスです。これらに client.request() を使う必要はありません。

ノードタイプエンドポイント
llm-chat/v1/llm-chat/generate
after-effects/v1/after-effects/generate
motion-graphics/v1/motion-graphics/generate
lottie-overlay/v1/lottie-overlay/generate
3d-title/v1/3d-title/generate
image-to-text/v1/image-to-text/describe
video-composer/v1/scene-graph/generate
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" のいずれかです。省略するか、そのモデルが対応していない段階を送信すると、モデルのデフォルトになります。推論の強度そのものに料金はありません。LLM の呼び出しはすべて、使ったトークンに応じて、それを処理したレーンでのモデルの単価で課金されるため、強度を上げると、書かれるトークンの分だけ高くなります。Claude モデルでは、どの段階でも、呼び出しが開発元の API 上で、そのレーンの単価で実行されます。モデルについてはテキスト生成 - あらゆる LLMを、課金についてはLLM 呼び出しの課金のしくみを参照してください。例外が 1 つあります。describe-to-picker と、そのテキスト版の text-to-picker は、このフィールドを省略し、llmModel が claude-opus-5.5 の場合、"high" で実行されます。その実行は、Anthropic 自身の API 上で、そのレーンの単価で行われます。変えるには別の段階を送ってください。ほかのモデルは、両者のデフォルトのモデルである Gemini 3.8 Flash も含め、モデルのデフォルトのままです。
  • advancedMode: true は、Gemini または Claude のモデルを、その開発元の API 上で直接実行します。temperature、maxTokens、推論の全範囲が完全に有効になるのは、そこだけです。呼び出しは、そのレーンのトークンあたりの単価で課金されます。このオプションがないモデルは、400 advanced_mode_unsupported を返します。モデル自体のプロバイダーがリクエストを受け付けられない間は、呼び出しはデフォルトの経路で実行されず、advanced_mode_unavailable を返します。事前なら 400、途中なら 502 で、後者はプロバイダーが試行に課金していなければ返還されます。モデルを実行するには、詳細モードをオフにしてください。例外は説明をピッカーへです。そこではプロバイダーが拒否した Claude の実行は、詳細モードがオフのときと同じく、Gemini 3.8 Flash にフォールバックします。
  • 動画のフレームレート。llm-chat は、referenceVideoFps(0 より大きく 24 以下)でより多くを指定しない限り、リファレンス動画を 1 秒あたり 1 フレーム読み取ります。これには Gemini モデルで advancedMode: true が必要です。ない場合、呼び出しは 400 video_fps_needs_advanced_mode を返します。フレームが多いほど、入力トークンも増えます。フレームレートは、モデルが動画の音声を聞く方法には影響しません。テキスト生成 - あらゆる LLMを参照してください。
  • 呼び出しの見積もり。client.credits.modelCosts([llmPriceKey(feature, model)]) は、一般的な呼び出しの見積もりを返し、estimates に一覧表示します。≈N と表示してください。llmPriceKey は @nodaro/shared/llm-models にあります。モデルとクレジットを参照してください。
  • ストリーミングはラップされていません。SDK は、テキスト生成 - あらゆる LLM ノードのストリーミングの応答を読み取りません。読み取り可能なストリームを使う 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 は拒否します。
  • Seedance 2.5 Flash(seedance-2-5-flash)は、より速く、より安い Seedance 2.5 です。1 回の呼び出しで最大 30 秒を 480p または 720p(既定)で作り、1080p は 720p でレンダリングされ、720p で課金されます。リファレンスは画像 10 枚、動画 5 本、オーディオ 5 本までで、それを超えると、何かを確保する前に 400 too_many_references になります。リファレンスのオーディオは、1 本が 2〜30 秒で、合計 30 秒までです。draft も seed もありません。run("video-to-video") の編集モデルでもあります。
  • MiniMax H3(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 のみです。
  • Gemini Omni Flash 1.2(gemini-omni-flash-1-2)は、秒単位の料金です。duration は 3〜15 の整数の秒数、解像度は 360p、720p、1080p、4k、aspectRatio は 16:9、9:16、auto を受け付けます。リファレンス画像は最大 6 枚で、ソース動画と一緒なら 5 枚です。開始フレームだけ、または 10 秒までの開始フレームと終了フレームは、正確なフレームになります。リファレンスがある場合や 10 秒を超える場合、フレームはリファレンスの一覧に加わり、プロンプトがそれを指定します。ソース動画は編集され、最大 15 秒の動画自体の長さで課金されます。範囲は videoTrimStart と videoTrimEnd で選びます。characterReferences は最大 2 件まで受け付けます。voice は使えず、開始フレームや終了フレームとは組み合わせられません。リファレンスの枠は使いません。クリップを編集するを参照してください。
  • Kling 4.0(kling-4)は、テキストだけでも、リファレンス素材からでも実行できます。受け取るのは、referenceImageUrls(最大 10 個)、referenceVideoUrls(最大 5 個、それぞれ 2〜30 秒)、characterReferences(最大 7 個、名前付きの被写体として)、referenceAudioUrls(最大 3 個)です。素材が全部で 15 個を超えると、何も確保される前に 400 になります。送った imageUrl や endFrameUrl は、リファレンス画像に加わります。kling-4 と kling-4-flash では、各キャラクターリファレンスは imageUrl、bodyImageUrl、最大 3 個の extraImageUrls から作られ、開始フレームと一緒に使えます。voice は拒否されます。keepOriginalSound: true は、リファレンス動画自体の音声を残します。デフォルトでは、最初のオーディオクリップがサウンドトラックとして再生されます。このクリップはもう 1 本のリファレンス動画として送られるので、実行はリファレンス動画を使う実行として課金され、ほかのクリップは名前付きの声のままです。audioSoundtrack: false にすると、すべてのクリップがボイスのサンプルのままになります。リファレンス動画を使う実行は、出力の秒数に、出力とクリップのうち長いほうの秒数を足した分が、リファレンス料金で課金されます。Kling 4.0 Keyframes(kling-4-keyframes)は、imageUrl、順番どおりの最大 8 個の中間フレームの referenceImageUrls、endFrameUrl を受け取ります。フレームの総数の上限は duration で決まり、3 秒で 4 個から、9 秒以上で 10 個までです。それを超えると 400 になります。どちらも duration は 3〜30(デフォルトは 5)、resolution は 720p または 1080p で、ほかの値は 720p でレンダリングされます。aspectRatio は auto、16:9、9:16、1:1、21:9 のいずれかです。オーディオは常にオンで、シードはありません。
  • Kling 4.0 Flash(kling-4-flash)は、Kling 4.0 の高速で低価格な版です。imageUrl だけの場合は、正確な開始フレームになります。それ以外はリファレンスモードで実行されます。プロンプトだけ、referenceImageUrls(最大 10 個)、referenceVideoUrls(最大 5 個、合計 2〜20 秒)、characterReferences(最大 7 個)、またはそれらと一緒の開始フレームです。リファレンスモードでは、素材は全部で 15 個までです。referenceAudioUrls の N 番目のクリップ(最大 7 個)が、characterReferences の N 番目のエントリの声になります。声を持たせるには、キャラクターに 2〜4 枚の画像、または videoUrl が必要です。そうでない場合、そのクリップは取り除かれ、最後のキャラクターより後のクリップも取り除かれます。duration は 3〜20(デフォルトは 5)で、出力は 720p だけです。ほかの値は 720p でレンダリングされます。終了フレーム、シード、audioSoundtrack はありません。
  • Kling 4.0 と Kling 4.0 Flash の動画の被写体。characterReferences のエントリーの videoUrl(キャラクターを映した 3〜8 秒のワンショットのクリップ)を指定すると、そのエントリーはその動画から作られた被写体になります。1 回のリクエストで最大 3 個です。クリップは 5 本のリファレンス動画の 1 本として数えられます。料金は画像だけのエントリーと同じなので追加料金はかからず、ほかのモデルはこれを拒否します。動画の被写体を参照してください。
  • PixVerse V6 Max(pixverse-v6-max)は、run("generate-video") で、imageUrl を正確な最初のフレームとして実行し、aspectRatio は送られません。run("text-to-video") では、aspectRatio に 16:9(デフォルト)、4:3、1:1、3:4、9:16、2:3、3:2、21:9 を使います。duration は 1〜15(デフォルトは 5)、resolution は 360p、540p、720p(デフォルト)、1080p(ほかの値は 720p)、seed は 0〜2147483647 です。sound: false(sound がない場合は generateAudio: false)でない限りネイティブ音声はオンで、料金が変わります。終了フレームとリファレンスはありません。
  • Grok Imagine 1.5(grok-imagine-video-1.5)には、正確な最初のフレームである imageUrl が必要です。endFrameUrl は正確な最後のフレームで、両方に同じ URL を使うと継ぎ目のないループになります。中間フレームは最大 4 枚まで、順番に referenceImageUrls に入れ、クリップ全体に秒単位で配置されます。D 秒のクリップは最大 D − 1 枚を受け付け、残りは省かれます。duration は 1〜15(デフォルトは 8)、resolution は 480p(デフォルト)、720p、1080p(ほかの値は 480p)で、seed はありません。1080p では imageUrl だけを受け付けます。終了フレーム、ループ、中間フレームがあると、クレジットが確保される前に 400 start_frame_only_resolution で拒否されます。それらには 720p を使ってください。
  • Gemini Omni と Gemini Omni Flash(gemini-omni-video と gemini-omni-flash)は、characterReferences で実在の人物の顔を保ちます。{ imageUrl, description, bodyImageUrl?, extraImageUrls?, name?, voice?, videoUrl? } のエントリーを最大 3 件渡します。voice は { preset, description?, exampleLine? } で、preset は @nodaro/shared の GEMINI_OMNI_VOICE_PRESETS の ID のいずれかです。クリップをまたいで、そのキャラクターの声を 1 つに保ちます。characterReferences を受け付けるのは、これらのモデルと gemini-omni-flash-1-2(最大 2 件、voice なし)、kling-4、kling-4-flash だけです。ほかのモデルは 400 を返します。Gemini Omni では、characterReferences は開始フレーム(imageUrl)と組み合わせられません。Gemini Omni と Gemini Omni Flash では、キャラクター 1 人は、モデルの 7 つの入力ユニットのうち 1 つ(bodyImageUrl があれば 2 つ)を使い、リファレンス画像とソース動画もそのユニットを共有します。キャラクターのリファレンスでクレジットは増えません。顔を同じに保つ必要がある場合は、referenceImageUrls の代わりにこちらを使ってください。

テキストから音声。provider を省略すると、テキストから音声は、10,000 文字までのテキストに ElevenLabs v4 を使います。それより長いテキストは、上限が 40,000 文字の ElevenLabs Turbo v2.5 にフォールバックするため、途中で切れることはありません。自分で指定した provider は、常にそのまま使われます。ElevenLabs v3 を使い続けるには、provider: "elevenlabs-v3" を送ってください。上限は 5,000 文字です。

クリップをまたいだ一貫性。 テキストから音声は、previousText と nextText も受け付けます。クリップの直前と直後に話されるセリフで、それぞれ最大 1,000 文字です。これらは読み上げられません。ElevenLabs v4、v4 Turbo、Turbo v2.5、Multilingual v2 は、これを使って、別々に作ったクリップのイントネーションを 1 つにそろえます。ElevenLabs v3 と Gemini の音声モデルはこれを無視します。

Gemini の音声モデル。provider には、gemini-3-8-flash-lite-tts、gemini-3-8-flash-tts、gemini-3-1-flash-tts、gemini-2-5-pro-tts も指定できます。各モデルは自身の名前付きボイスだけを話し、それらは voices.list({ model }) で一覧できます。ほかの voice は、何も請求される前に 400 になります。テキストが言語を決めるため languageCode は受け付けず、タイミングも返しません。styleDirection は、テキストの話し方を指定します。3.8 では自由なテキスト、3.1 と 2.5 ではモデルのスタイルのいずれかで、3.1 と 2.5 は pace、accent、audioProfile も受け付けます。各モデルのリストは、@nodaro/shared の能力シート getTtsCapabilities(provider).direction にあります。指示は読み上げられず、課金もされません。料金は 1,000 文字ごとです。テキストから音声を参照してください。

タイミングと音声ファイル。 withTimestamps: true を付けると、完了したジョブの output_data.transcript に、単語ごとのタイミング(startMs と endMs を持つ words[])が入ります。追加のクレジットはかかりません。outputFormat では音声ファイルを選べます。mp3_44100_128(デフォルト)、より高いビットレートの MP3 である mp3_44100_192、非圧縮の WAV である wav_24000 のいずれかです。クレジットはどの形式でも同じです。ジョブの audioUrl は、実際に返ってきたファイルに合わせて .mp3 か .wav で終わり、output_data.audioMimeType がその種類(audio/mpeg または audio/wav)を示します。ダウンロードするファイルの名前は、指定した形式ではなく、このフィールドから決めてください。値は @nodaro/shared/models の TTS_OUTPUT_FORMATS にあります。

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

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

よくある質問

Nodaro の SDK で画像を生成するには、どうすればよいですか?

ノードタイプ generate-image と prompt を指定して、client.nodes.runAndWait を呼び出します。ジョブの出力で解決され、その imageUrl が生成された画像です。

run と runAndWait の違いは何ですか?

run はノードを開始し、すぐに jobId を返します。runAndWait はノードを開始し、2 秒ごとにジョブをポーリングして、ジョブが完了すると出力で解決されます。

runAndWait は、どのくらいの時間待機しますか?

デフォルトでは最大 15 分です。maxMs オプションで変更できます。タイムアウトしてもジョブはキャンセルされず、通常はサーバー側でそのまま完了します。

どのノードタイプを実行できますか?

client.nodes.list() を呼び出すと、サーバーが対応するすべてのノードタイプを、カテゴリー、出力タイプ、モデル、クレジットの料金とともに取得できます。ノードリファレンスのすべてのノードには、API のタイプがあります。

1 回の呼び出しで複数の画像を生成するには、どうすればよいですか?

generate-image と、count(1〜4 枚の画像)または models(2〜4 個の画像モデル)を指定して、client.nodes.runBatchAndWait を呼び出します。バッチは全体として課金されるか、まったく課金されないかのどちらかで、1 枚の画像が失敗しても、ほかの画像が破棄されることはありません。

リクエストを再試行するときに、二重に課金されないようにするには、どうすればよいですか?

run または runAndWait のオプションで idempotencyKey を指定し、再試行するときは同じキーを再利用します。プラットフォームは、2 回目の実行を開始する代わりに、最初の実行を返します。

最終更新

目次