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

TypeScript SDK

@nodaro/sdk をインストールし、API トークンで認証して、Node.js、ブラウザー、エッジランタイムの TypeScript から、Nodaro のノードとワークフローを実行します。

Nodaro TypeScript SDK は、Nodaro REST API の型付きクライアントで、npm に @nodaro/sdk として公開されています。単体のノードとワークフロー全体を実行してその結果を待ち、キャラクター、ボイス、メディアなどを管理します。Node.js、ブラウザー、エッジランタイムで動作し、API のすべてのエラーは、キャッチできる型付きのエラークラスとして届きます。

インストール

npm install @nodaro/sdk
  • このパッケージは、Apache-2.0 ライセンスのオープンソースです。npm の @nodaro/sdk と GitHub 上のソースを参照してください。
  • ES モジュールと CommonJS のビルドを、TypeScript の型定義とともに提供します。
  • Node.js 20 以降が必要です。また、グローバルな fetch と URL を持つランタイム、つまり最新のブラウザー、React Native、Cloudflare Workers、Deno、Bun でも動作します。
  • ほかに 2 つの Nodaro パッケージが一緒にインストールされます。通信形式の型とモデルカタログを含む @nodaro/shared と、プロンプト用のヘルパーを含む @nodaro/prompts です。
  • @supabase/supabase-js と @supabase/ssr は、省略可能なピア依存関係です。supabaseAuth または @nodaro/sdk/supabase を通じて Supabase でユーザーをログインさせるブラウザーアプリの場合にだけ、インストールしてください。
  • Nodaro CLI はこの SDK の上に構築されているため、CLI のコマンドと SDK の呼び出しは、同じエンドポイントを呼び出します。

API トークンを取得する

トークンを作成する

Nodaro にログインし、設定 › APIトークンを開いて、トークンを作成をクリックします。

表示されたときにコピーする

トークンは ndr_ で始まり、表示されるのは 1 回だけです。Nodaro はそのハッシュしか保存しないため、なくしたトークンをもう一度表示することはできません。代わりに、新しいトークンを作成してください。

コードに含めない

トークンは、NODARO_TOKEN のような環境変数か、シークレットマネージャーに保存してください。クライアント側のコードには、絶対に含めないでください。

個人用トークンは、あなた自身として動作します。ほかの人の代わりに動作させたい場合、たとえば多くのユーザーが接続するアプリでは、代わりに OAuth を使ってください。認証で、すべての選択肢を比較しています。

最初の呼び出しをする

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

const { data: nodes } = await client.nodes.list()
console.log(`${nodes.length} node types available`)

client.nodes.list() は無料で、スコープも不要なため、接続を最初に確認するのに適しています。セルフホスティング環境では、baseUrl に自分のインスタンスのアドレスを設定します。Nodaro と同じオリジンから配信されるブラウザーアプリでは、空文字列を使います。クライアントに、createClient のすべてのオプションが一覧表示されています。

画像を生成し、それから動画を生成する

const image = await client.nodes.runAndWait("generate-image", {
  prompt: "A snow leopard resting on a rock at sunrise",
  provider: "nano-banana-2",
})
console.log(image.imageUrl)

const video = await client.nodes.runAndWait("generate-video", {
  prompt: "The snow leopard slowly turns its head toward the camera",
  imageUrl: image.imageUrl,
  provider: "seedance-2-fast",
  duration: 4,
})
console.log(video.videoUrl)

runAndWait は実行を開始し、ポーリングして、ジョブの出力で解決されます。画像には imageUrl、動画には videoUrl、オーディオには audioUrl です。最初の呼び出しは、画像生成(Generate Image)ノードを Nano Banana 2 上で実行します。2 番目の呼び出しは、その画像を動画生成(Generate Video)ノードで、Seedance 2 Fast 上でアニメーション化します。

provider を省略すると、ノードのデフォルトのモデルが使われます。各ノードページには、実行できるモデルとそのクレジット料金が一覧表示されており、client.models.list() は、同じカタログをコードから返します。モデルとクレジットを参照してください。

実行の仕組み

生成は非同期です。リクエストはワーカー上でジョブを開始し、すぐに返ります。結果は、数秒後か数分後に届きます。

呼び出すもの返るもの次にすること
client.nodes.run(type, params){ jobId }ステータスが completed、failed、cancelled のいずれかになるまで、client.jobs.getStatus(jobId) をポーリングします。
client.nodes.runAndWait(type, params, opts)ジョブの出力何もありません。SDK が、最大 15 分間、2 秒ごとにポーリングします。
client.nodes.runMany(type, paramsList, opts)リクエストごとに 1 つの { jobId, output }何もありません。実行はまとめて開始され、結果は入力と同じ順番で返ります。
client.workflows.run(id){ executionId, status }実行が終わるまで、client.executions.get(executionId) をポーリングします。

テキストを結合(Combine Text)のような一部のノードタイプは、インラインで実行され、jobId なしに結果を直接返します。ノードの実行で、すべての実行メソッドを説明し、ジョブと実行で、ステータスを説明しています。

進行状況を表示し、ユーザーが待つのを止められるようにする

import { JobAbortedError } from "@nodaro/sdk"

const controller = new AbortController()
stopButton.onclick = () => controller.abort()

try {
  const clip = await client.nodes.runAndWait(
    "generate-video",
    { prompt: "Waves roll onto a black sand beach", provider: "seedance-2-fast", duration: 4 },
    {
      signal: controller.signal,
      onProgress: (status) => setProgressBar(status.progress ?? 0),
    },
  )
  showVideo(clip.videoUrl)
} catch (err) {
  if (err instanceof JobAbortedError && err.jobId) {
    await client.jobs.cancel(err.jobId)
  } else {
    throw err
  }
}

onProgress は、ポーリングのたびにジョブのステータスを受け取り、モデルが報告する場合は progress が 0 から 100 になります。シグナルをアボートしても、待機が止まるだけです。ジョブは、client.jobs.cancel(jobId) でキャンセルするまで実行を続けます。このキャンセルは、確保されていたクレジットも返還します。

各結果は、届いた時点ですぐに表示してください。2 段階のフローでは、動画のステップを実行している間に、画像を表示してください。

認証方法を選ぶ

プロバイダー使うときトークンの取得元
StaticTokenAuth1 つの固定トークンを使うサーバーのコードですAPI トークン(ndr_...)または OAuth アクセストークン(ndr_app_...)
CallbackAuthトークンの更新やローテーションを自分で行う場合ですリクエストごとに呼び出される、自分の関数です
supabaseAuth同じ Nodaro インスタンスにユーザーがログインするブラウザーアプリですユーザーの現在のセッションです

すべてのリクエストは、プロバイダーにトークンを求め、Authorization: Bearer <token> として送信します。プロバイダーが null を返した場合、リクエストはヘッダーなしで送られます。各プロバイダーと、ブラウザー特有のルールについては、認証を参照してください。

エラーを処理する

API がエラーで応答すると、すべてのメソッドは NodaroError の型付きサブクラスをスローします。具体的なクラスから先にキャッチし、NodaroError は最後にキャッチしてください。

import {
  InsufficientCreditsError,
  NodaroError,
  RateLimitedError,
  UnauthorizedError,
} from "@nodaro/sdk"

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    showPaywall({ required: err.required, available: err.available })
  } else if (err instanceof UnauthorizedError) {
    askForANewToken()
  } else if (err instanceof RateLimitedError) {
    retryLater()
  } else if (err instanceof NodaroError) {
    console.error(`API error ${err.status} (${err.code}): ${err.message}`)
  } else {
    throw err // a network failure, not an API answer
  }
}

すべての NodaroError には、message、insufficient_credits のような安定した code、HTTP の status があります。エラーに、すべてのクラスとスローされる条件が一覧表示されています。

よく使うレシピ

ワークフローを実行して待つ

client.workflows.run() は、ワークフロー内のすべてのノードを 1 回実行する実行を開始し、すぐに返ります。ステータスが終了状態になるまで、client.executions.get() をポーリングします。

const { executionId } = await client.workflows.run(workflowId)

for (;;) {
  const { data } = await client.executions.get(executionId)
  console.log(`${data.completedNodes}/${data.totalNodes} nodes done`)

  if (["completed", "failed", "cancelled", "timed_out"].includes(data.status)) {
    if (data.status !== "completed") throw new Error(data.errorMessage ?? data.status)
    console.log(`Done. Used ${data.totalCreditsUsed} credits.`)
    break
  }
  await new Promise((resolve) => setTimeout(resolve, 2_000))
}

一部のノードだけを実行するには、第 2 引数として { nodeIds: [...] } を渡します。ワークフローとプロジェクトを参照してください。

複数の候補を一度に生成する

const results = await client.nodes.runMany("generate-image", [
  { prompt: "A lighthouse at dawn, watercolor" },
  { prompt: "A lighthouse at dusk, watercolor" },
  { prompt: "A lighthouse in a storm, watercolor" },
])
for (const { jobId, output } of results) console.log(jobId, output.imageUrl)

runMany は、いずれかの実行が失敗すると拒否されます。モデルに最も良い結果を選ばせるには、URL を client.reduce.run() に渡します。

ファイルをアップロードして使う

const upload = await client.uploads.upload(file) // a File, in the browser or Node.js
const portrait = await client.nodes.runAndWait("generate-image", {
  prompt: "The same person as a watercolor portrait",
  referenceImageUrls: [upload.url],
})

アップロードすると、画像、動画、オーディオの URL を受け取るどのノードにも渡せる、公開の url が返ります。メディアとアップロードを参照してください。

実行前に料金を確認する

const { total } = await client.credits.balance()
const { data: prices } = await client.credits.modelCosts(["nano-banana-pro", "nano-banana-pro:4K"])

if (total < prices["nano-banana-pro:4K"]) showPaywall()

料金と残高は、Nodaro Cloud に存在します。モデルとクレジットとクレジットを参照してください。

生成前にプロンプトを改善する

const { prompt } = await client.promptHelper.enhance({
  nodeType: "generate-image",
  prompt: "snow leopard on a rock",
})

プロンプトウィザードは、指定したノード向けに、大まかなアイデアを詳細なプロンプトに書き直します。呼び出しごとにクレジットがかかります。

AI コーディングアシスタントで SDK を使う

  • Claude Code プラグイン。/plugin marketplace add nodaroai/app.nodaro.ai を実行し、続けて /plugin install nodaro を実行します。このプラグインは、SDK のパターン、モデル、クレジットを把握したスキルを追加し、Nodaro のホスト型 MCP サーバーに接続します。エージェントスキルを参照してください。
  • ほかのアシスタント。npm のパッケージの README は、コーディングアシスタント向けに書かれた短い説明から始まります。これを、依頼内容とともに Cursor やほかのアシスタントに貼り付けてください。
  • コードをまったく書かない場合。アシスタントに代わりに Nodaro を実行させるには、MCP 経由で接続します。

リファレンス

SDK は、REST API と同じエンドポイントをラップしています。まだ SDK のメソッドがないエンドポイントは、同じ認証と型付きエラーを保つ client.request() で呼び出してください。

よくある質問

最終更新

目次