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

クライアント

createClient で Nodaro SDK のクライアントを作成し、ベース URL、認証、タイムアウト、ワークスペースを設定して、クライアントが公開するすべてのリソースを確認します。

クライアントは、createClient() が返すオブジェクトです。NodaroClient は、あなたのベース URL、認証プロバイダー、設定を保持し、client.workflows や client.nodes のように、Nodaro API のあらゆる部分をリソースとして公開します。クライアントは 1 回作成し、すべての呼び出しで再利用します。

クライアントを作成する

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

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

プロパティ

型

NodaroClient はクラスとしてもエクスポートされているため、クライアントを受け取る関数の型を書けます。

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

async function countWorkflows(client: NodaroClient, projectId: string) {
  const { data } = await client.workflows.list({ projectId })
  return data.length
}

クライアントのリソース

各リソースは createClient によって作成され、client.<resource> としてアクセスします。

リソース内容リファレンス
client.workflowsワークフロー:作成、更新、共有、エクスポート、インポート、実行ワークフローとプロジェクト
client.projectsワークフローを入れるプロジェクトワークフローとプロジェクト
client.sessionsプロジェクト内の生成セッションワークフローとプロジェクト
client.executionsワークフロー全体の実行ジョブと実行
client.jobs単体の生成ジョブ(評価とフィルター付き)ジョブと実行
client.webhooksジョブが終わったときに Nodaro が呼び出すエンドポイントジョブと実行
client.videoPro動画生成 Proの実行を停止または継続ジョブと実行
client.nodesノードカタログと単体のノード実行ノードを実行する
client.apps公開されたアプリとその実行アプリとテンプレート
client.templatesテンプレートマーケットプレイスアプリとテンプレート
client.tutorialsチュートリアル動画とチュートリアルワークフローアプリとテンプレート
client.llm言語モデルからの構造化出力LLM と Reduce
client.reduce複数の結果から最良のものを選ぶか、組み合わせるLLM と Reduce
client.uploadsファイルのアップロードメディアとアップロード
client.library保存済みのメディアメディアとアップロード
client.gallery公開ギャラリーとお気に入りメディアとアップロード
client.mediaメディアのダウンロード、トリミング、キャプション、オーバーレイ、コラージュメディアとアップロード
client.voicesボイス、ボイスチェンジャー、ボイスデザイン、吹き替えボイスと音声
client.dubbing吹き替えを作成し、そのセリフと字幕を読み取り、言語を追加しますボイスとオーディオ
client.audio音声の分離、抽出、ミックス、トリミング、文字起こしボイスと音声
client.edit1 回の呼び出しでのポッドキャスト編集(引き締め、チャプター、予告編、クリップ、スピーカーレイアウト)、無音検出、オーディオ同期、カメラ切り替え、編集プラン、EDL レンダリング編集
client.scene3d編集可能な 3D シーンと 3D レンダリング Pro3D シーン
client.charactersキャラクターキャラクター
client.locationsロケーションロケーション
client.objectsオブジェクトと小道具オブジェクトとクリーチャー
client.creatures動物とクリーチャーオブジェクトとクリーチャー
client.community共有されたコミュニティのアセットライブラリコミュニティライブラリ
client.studioスタジオプロダクションスタジオプロダクション
client.shots共有リンクの背後にある共有ショットレコードスタジオプロダクション
client.recastRecast の実行と、自分で書いたスクリプトRecast
client.videoRemake短い動画の人物、ペット、商品、場所を置き換えます。Nodaro Cloud のみVideo Remake
client.trends既製の Video Remake のレシピを、自分の写真で実行します。Nodaro Cloud のみTrends
client.pipelinesストーリーから動画へのパイプラインパイプライン
client.copilotNodaro アプリ内限定の Copilot スレッドCopilot
client.modelsモデルカタログモデルとクレジット
client.credits残高とモデルの価格モデルとクレジット
client.billingプラン、価格、サブスクリプションモデルとクレジット
client.pickerCatalogs各ピッカーの有効なオプションピッカー、プリセット、プロンプト
client.catalogsすべてのピッカーカタログを 1 回の呼び出しでピッカー、プリセット、プロンプト
client.presets保存済みのノードプリセットと標準プリセットピッカー、プリセット、プロンプト
client.palettesカラーパレットピッカー、プリセット、プロンプト
client.moodboardsムードボードピッカー、プリセット、プロンプト
client.promptHelperプロンプトウィザードピッカー、プリセット、プロンプト
client.organizations組織、メンバー、招待組織とワークスペース
client.workspacesワークスペース、メンバー、参加コード組織とワークスペース
client.userSettings自分自身の設定:言語、ギャラリーの公開範囲、ノードメニューとキャンバスの設定、月次の明細メールユーザー設定
client.surfaceこのデプロイメントが提供するもの:ノードタイプ、モデル、ワールドSurface
client.developerAppsあなたが所有する OAuth アプリOAuth と開発者アプリ
client.oauthコード交換、トークンの取り消し、同意画面用のデータOAuth と開発者アプリ

クライアント自体には、さらに 5 つのメソッドがあります。me()、connectedApps()、revokeConnectedApp()、withWorkspace()、request() です。

リソースごとのエントリーポイント

ルートの @nodaro/sdk は、すべてをエクスポートします。各リソースは、独自のエントリーポイント @nodaro/sdk/<entry> としても公開されています。このエントリーポイントは、そのリソースと、リソースが受け取って返す型だけを読み込みます。たとえば、@nodaro/sdk/jobs、@nodaro/sdk/nodes、@nodaro/sdk/workflows です。

  • @nodaro/sdk/client には、createClient、NodaroClient、認証プロバイダーが含まれます。
  • @nodaro/sdk/core には、NodaroClientCore と、同じ認証プロバイダーが含まれます。
  • @nodaro/sdk/errors には、エラークラスと throwFromResponse が含まれます。
  • ほかのエントリーは、すべてリソースの名前が付いています。@nodaro/sdk/node-presets は client.presets です。@nodaro/sdk/webhooks には、verifyWebhookSignature も含まれます。
import { NotFoundError } from "@nodaro/sdk/errors"
import type { Job, JobStatus } from "@nodaro/sdk/jobs"

エントリーからインポートした値は、ルートからインポートした値と同じです。そのため、それぞれの側がどちらのパスを使っても、instanceof NotFoundError は機能します。createClient はすべてのリソースを作成するため、@nodaro/sdk/client はすべてのリソースを読み込みます。以前からあるサブパス @nodaro/sdk/supabase と @nodaro/sdk/signup-signals は変わりません。

使うリソースだけを持つクライアント

NodaroClientCore は、リソースを持たないクライアントです。createClient が受け取るオプション、リクエストのメソッド、me()、connectedApps()、revokeConnectedApp() を持ちます。NodaroClient は、これをすべてのリソースで拡張したものです。呼び出すリソースだけで自分で拡張すると、ほかのリソースのモジュールは一切読み込まれません。

import { NodaroClientCore, StaticTokenAuth } from "@nodaro/sdk/core"
import { JobsResource } from "@nodaro/sdk/jobs"
import { NodesResource } from "@nodaro/sdk/nodes"

class AppClient extends NodaroClientCore {
  readonly jobs = new JobsResource(this)
  readonly nodes = new NodesResource(this) // polls through `jobs`
}

const client = new AppClient({ baseUrl: "https://app.nodaro.ai", auth: new StaticTokenAuth(token) })
await client.nodes.runAndWait("generate-image", { prompt: "a lighthouse at dusk" })

どのリソースクラスも、NodaroClientCore を受け取ります。NodesResource には同じクライアント上の jobs が、Scene3DResource には nodes が必要です。コンストラクターの型がそれを示しているため、どちらかを省くとコンパイルに失敗します。withWorkspace は NodaroClient のメソッドです。ワークスペースで作業するには、コンストラクターに workspaceId を渡してください。

メソッドが返すもの

  • エンベロープはそのまま保たれます。エンドポイントが { "data": ... } で応答する場合、メソッドはそのエンベロープをそのまま返すため、const { data } = await client.workflows.get(id) のように書きます。ページ分割された一覧では、data の横に nextCursor のようなカーソルが加わります。
  • 一部のリソースは、内容をそのまま返します。いくつかのメソッドは、レスポンスを展開して返します。たとえば client.characters.list() は { characters, nextCursor } を返し、client.credits.balance() は残高そのものを返します。正確な戻り値の型は、各リファレンスページに示されています。
  • 削除とキャンセルは、通常 { success: true } を返します。
  • フィールド名は、通信時の形式に従います。Job は、API がその形で送るため、output_data や created_at のような snake_case のフィールドを使います。Workflow と WorkflowExecution は camelCase を使います。

すべてのレスポンスと入力の型はエクスポートされているため、import type でインポートできます。型を参照してください。

me()

me(): Promise<UserIdentity & MeOrganizations>

現在のトークンの持ち主の情報を返します(GET /v1/me)。有効なトークンであれば、API トークン、OAuth アクセストークン、ブラウザーセッションのいずれであっても、その所有者を返します。トークンがない場合や無効な場合は、UnauthorizedError をスローします。

const me = await client.me()
console.log(me.email, me.tier)
フィールド型説明
idstringNodaro のユーザー ID です。
emailstringユーザーのメールアドレスです。
displayNamestring | null表示名です。設定されていない場合は null です。
avatarUrlstring | nullアバターの URL です。設定されていない場合は null です。
tierstring保存されているサブスクリプションのティアで、"free" や "pro" などです。実際に適用されるティア(従量課金を含む)については、client.credits.balance() の effectiveTier を読み取ってください。
isAdminbooleanユーザーが管理者かどうかです。表示内容を決めるためだけに使ってください。権限のチェックは、サーバー自身がすべて行います。

組織機能のある Nodaro Cloud インスタンスでは、結果に organizations、workspaces、lastWorkspaceId、organizationsUnavailable も含まれます。この 3 つの状態は、それぞれ異なる扱いが必要です。

見えるもの意味対応
フィールドがないインスタンスに組織機能がありませんワークスペース切り替えを表示しないでください。
フィールドはあるが空アカウントがどの組織にも属していません組織の作成または参加を提案してください。
organizationsUnavailable: true参照に失敗しましたそれまでの選択をそのまま保ってください。アクセスを失ったとユーザーに伝えないでください。

connectedApps()

connectedApps(): Promise<ConnectedApp[]>

サインインしているユーザーのアカウントにアクセスできるすべてのアプリを、新しい許可から順に返します(GET /v1/me/connected-apps)。一覧には、開発者アプリ、AI アシスタントの MCP コネクタ、セルフホスティングのインストールが含まれます。接続済みアプリの設定画面の元になるデータです。許可とは何かについては、OAuth を参照してください。

このメソッドには、サインイン済みのブラウザーセッションが必要です。 supabaseAuth() または createSharedSupabaseClient のセッショントークンを受け付けます。API トークン(ndr_…)やアプリのトークン(ndr_app_…)は UnauthorizedError で拒否されるので、アプリは自分が使っている許可を一覧表示したり取り消したりできません。サーバー側の連携からは呼び出せません。

const apps = await client.connectedApps()
// [{ authorizationId, name, kind, homepageUrl, scopes, connectedAt, lastUsedAt, grantedBy? }]
フィールド型説明
authorizationIdstring許可です。revokeConnectedApp() に渡します。
namestring | nullアプリの名前です。自分自身を登録した MCP クライアントは、自分で名前を選んでいます。
kindDeveloperAppKinduser(開発者アプリ)、first_party_mcp、dynamic_mcp(自分自身を登録した MCP クライアント)、community_instance(セルフホスティングのインストール)のいずれかです。
homepageUrlstring | nullアプリのホームページです。アプリが指定した場合だけ入ります。
scopesDeveloperAppScope[]許可が持つスコープです。
connectedAtstringユーザーがアクセスを許可した日時で、ISO 8601 形式です。
lastUsedAtstring | nullその許可で発行されたいずれかのトークンが最後に使われた日時です。一度も使われていない場合は null です。
grantedBy"assertion_exchange"、任意アプリが同意画面なしで、デプロイメント自身のアプリケーションのための交換を通じて得た許可に含まれます。ユーザーが承認した許可には含まれません。

revokeConnectedApp(authorizationId)

revokeConnectedApp(authorizationId: string): Promise<void>

アプリのアクセスを終了します(POST /v1/me/connected-apps/:authorizationId/revoke)。許可と、その許可で発行されたすべてのトークンを一度に取り消すので、アプリの次の呼び出しは 401 で失敗します。connectedApps() と同じく、サインイン済みのブラウザーセッションが必要です。許可がユーザーのものでない場合や、すでに取り消されている場合は、NotFoundError をスローします。

await client.revokeConnectedApp(app.authorizationId)

client.userSettings

client.userSettings は、サインインしている人自身の設定を読み取り、変更します。インターフェースの言語、ギャラリーの公開範囲、ノードメニューとキャンバスの設定、月次の明細メールです。@nodaro/sdk/user-settings としてインポートすることもできます。アプリは必要な設定を表示し、変更したフィールドだけを送り返します。

メソッドエンドポイント備考
get()GET /v1/user/settingsUserSettings を返します:{ tier, publicOutputs, promptTemplates, textTemplates, preferredLocale, mcpPreferences, showRecentNodes, showMostUsedNodes, variableDisplayMode, nodeDoubleClickAction, monthlyStatementEmail }。誰もサインインしていない場合は UnauthorizedError をスローします。
update(patch)PATCH /v1/user/settings送ったフィールドだけを変更し、保存された設定を tier なしで返します。

update(patch) のルール:

  • promptTemplates と textTemplates は、保存されている値を丸ごと置き換えるので、マップまたはリスト全体を送ってください。サーバーが知らないテンプレートのキーや、デフォルトと同じ値は破棄されます。
  • mcpPreferences は、軸ごとにマージされます。null を送るとそのフィールドが消去されます。たとえば update({ mcpPreferences: { image: { model: null } } }) です。MCP ツールは、そのフィールドに自身の既定値を使うようになります。パッチの型は UserMcpPreferencesPatch です。
  • Nodaro Cloud で publicOutputs: false にするには、Standard プラン以上が必要です。そうでない場合は ForbiddenError をスローします。
  • preferredLocale は、Nodaro が提供する言語のいずれかです(UserSettingsLocale)。
  • 無効な値、または変更するものがないパッチは、ステータス 400(validation_error)の NodaroError をスローします。プロフィールがない場合は NotFoundError をスローします。
// The monthly statement toggle on a billing screen.
const { monthlyStatementEmail } = await client.userSettings.get()
await client.userSettings.update({ monthlyStatementEmail: !monthlyStatementEmail })

型は UserSettings、UserSettingsPatch、UserSettingsSaved、UserSettingsLocale、UserTextTemplate、UserMcpPreferences、UserMcpPreferencesPatch、VariableDisplayMode、NodeDoubleClickAction です。

1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、tier はデプロイメントのプラン、つまり請求アカウントのティアで、publicOutputs をオフにできるかどうかもそのプランに従います。

client.surface

client.surface は、このデプロイメントが呼び出し元に提供するもの、つまりアプリが画面上でその人に表示すべきノードタイプ、モデル、Web Scrape のソース、ワールドを返します。答えは問い合わせた人によって変わるので、共有キャッシュには入りません。サインインしていなければ、一般ユーザーへの答えになります。@nodaro/sdk/surface としてもインポートできます。

メソッドエンドポイント補足
availability()GET /v1/surface/availabilitySurfaceAvailability を返します:{ nodes: { denied, hiddenFromUsers }, models: { denied, restricted }, webScrapeSources: { denied, hiddenFromUsers }, worlds }。hiddenFromUsers は管理者以外には空です。models.restricted は、デプロイメントが提供するモデルを制限している場合に true です。管理者がオフにしたモデルは拒否されますが、制限には当たりません。古いサーバーは restricted を省略します。その場合は false と読んでください。worlds は、すべてのワールド(SurfaceAvailabilityWorld:{ id, enabled })をデプロイメントの表示順で並べたもので、新しいサーバーでは増えることがあります。デプロイメントがワールドを通し、そのワールドが実行するすべてのノードタイプを呼び出し元が使える場合に、ワールドは enabled になります。
// The shared header shows only the worlds this person can use.
const { worlds } = await client.surface.availability()
const tabs = worlds.filter((w) => w.enabled).map((w) => w.id)

フィールドの説明はこのデプロイメントが提供するものにあります。

withWorkspace(workspaceId)

withWorkspace(workspaceId: string | null): NodaroClient

workspaceId で動作する新しいクライアントを返します。新しいクライアントは、元のクライアントの認証、ベース URL、タイムアウト、fetch を共有します。個人スペースを使うには null を渡します。

const classroom = client.withWorkspace(workspaceId)

await classroom.workflows.run(workflowId) // runs in the workspace
await client.workflows.run(workflowId)    // runs in the personal space

このメソッドは、現在のクライアントを変更するのではなく、新しいクライアントを返します。そのため、1 つのクライアントで同時に実行される 2 つの操作が、ワークスペースを取り違えることはありません。

ワークスペースが決めるのはスコープであって、アクセス権ではありません。一覧がどのワークスペースから読み取るか、新しいアイテムがどこに作られるかを決めます。ID で指定したアイテムの読み取り、変更、削除、実行は、そのアイテム自身のワークスペースによって決まります。ワークスペースの指定を忘れても自分の作業が見えなくなることはなく、間違ったワークスペースを指定しても、ほかの人の作業にアクセスすることはできません。

ワークスペースは、Nodaro Cloud の組織に属します。組織とワークスペースとワークスペースを参照してください。

request(method, path, options)

request<T>(method: string, path: string, options?: {
  body?: unknown
  query?: Record<string, string | number | boolean | undefined>
  headers?: Record<string, string>
  signal?: AbortSignal
}): Promise<T>

任意のエンドポイントにリクエストを送ります。まだリソースメソッドがない、ごく一部のエンドポイント向けです。あなたの認証ヘッダーとワークスペースを追加し、body を JSON として送信し、timeoutMs を適用して、リソースメソッドと同じ型付きエラーをスローします。

// The same request that client.jobs.list() sends
const page = await client.request<{ data: unknown[]; next: string | null }>("GET", "/v1/jobs", {
  query: { type: "llm-structured", limit: 20 },
})

FormData のボディは、マルチパートアップロードとして送信されます。undefined のクエリ値は除外されます。すべてのエンドポイントとそのフィールドは、REST API リファレンスに一覧があります。

タイムアウトと独自の fetch

timeoutMs は、上限(デフォルトは 60 秒)を超えたリクエストを中断します。ほとんどの生成は、妥当な HTTP タイムアウトよりも長くかかるため、生成を開始してジョブをポーリングしてください。client.nodes.runAndWait() は、その両方を代わりに行います。ストリーミングを行うメソッドである client.copilot.stream() と client.media.downloadVideoProgress() は、数分間開いたままになることを想定しているため、タイムアウトを適用しません。

独自の fetch を渡すと、リクエストの送り方を変えられます。

  • テスト。モックから、用意した Response オブジェクトを返します。
  • リトライ。グローバルな fetch を、5xx の応答でリトライするヘルパーでラップします。
  • トレーシング。トレーシングやモニタリングのライブラリでラップします。
const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  fetch: (input, init) => tracedFetch(input, init),
})

ランタイムとブラウザー

SDK が使うのは fetch と URL だけです。これらは、Node.js 20 以降、最新のブラウザー、React Native、Cloudflare Workers、Deno、Bun でグローバルに使えます。ポリフィルは必要ありません。

  • OAuth トークンでの CORS。OAuth アクセストークンで Nodaro を呼び出すブラウザーアプリは、開発者アプリの allowedOrigins に登録されたオリジンで動作する必要があります。OAuth と開発者アプリを参照してください。
  • セッションでの CORS。supabaseAuth を使うブラウザーアプリは、そのリストと照合されません。
  • クライアントラベル。サーバーでは、SDK は X-Nodaro-Client: sdk/<version> を送信し、Nodaro はこれを各ジョブの発信元として記録します。ブラウザーでは、ブラウザーの Origin ヘッダーが既にあなたのアプリを示しているため、デフォルトのラベルは送信されません。自分で設定した clientLabel は、常に送信されます。

よくある質問

Nodaro SDK では、どのベース URL を使えばよいですか?

Nodaro Cloud では https://app.nodaro.ai を使い、セルフホスティング環境では、そのインスタンスのアドレスを使います。Nodaro と同一オリジンで配信されるブラウザーアプリでは、空の文字列を使います。

デフォルトのリクエストタイムアウトはどれくらいですか?

60 秒です。timeoutMs オプションで変更できます。生成はどのリクエストよりも長くかかるため、タイムアウトを延ばすのではなく、生成を開始してジョブをポーリングしてください。

ワークスペースでリクエストを送るにはどうすればよいですか?

client.withWorkspace(workspaceId) を呼び出します。そのワークスペースであらゆるリクエストを送る新しいクライアントが返され、元のクライアントは、引き続き個人スペースで動作します。

SDK にメソッドがないエンドポイントを呼び出すには、どうすればよいですか?

client.request(method, path, options) を使います。ほかのリソースメソッドと同じ認証ヘッダーを送り、同じタイムアウトを適用し、同じ型付きエラーをスローします。

最終更新

目次