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 トークンを取得する
表示されたときにコピーする
トークンは 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 段階のフローでは、動画のステップを実行している間に、画像を表示してください。
認証方法を選ぶ
| プロバイダー | 使うとき | トークンの取得元 |
|---|---|---|
StaticTokenAuth | 1 つの固定トークンを使うサーバーのコードです | 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 経由で接続します。
リファレンス
クライアント
createClient、すべてのオプション、ワークスペース、リソースの全リストです。
認証
StaticTokenAuth、CallbackAuth、supabaseAuth、共有ブラウザーセッションです。
エラー
すべてのエラークラスと、そのステータス、コード、復旧方法です。
ノードの実行
run、runAndWait、runMany を、型付きパラメーターとともに説明します。
ワークフローとプロジェクト
ワークフローの作成、更新、共有、エクスポート、実行です。
ジョブと実行
実行のポーリング、一覧表示、キャンセル、削除です。
SDK は、REST API と同じエンドポイントをラップしています。まだ SDK のメソッドがないエンドポイントは、同じ認証と型付きエラーを保つ client.request() で呼び出してください。
よくある質問
関連ページ
クライアント
認証
ノードの実行
エラー
REST API の概要
最終更新