クライアント
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.edit | 1 回の呼び出しでのポッドキャスト編集(引き締め、チャプター、予告編、クリップ、スピーカーレイアウト)、無音検出、オーディオ同期、カメラ切り替え、編集プラン、EDL レンダリング | 編集 |
client.scene3d | 編集可能な 3D シーンと 3D レンダリング Pro | 3D シーン |
client.characters | キャラクター | キャラクター |
client.locations | ロケーション | ロケーション |
client.objects | オブジェクトと小道具 | オブジェクトとクリーチャー |
client.creatures | 動物とクリーチャー | オブジェクトとクリーチャー |
client.community | 共有されたコミュニティのアセットライブラリ | コミュニティライブラリ |
client.studio | スタジオプロダクション | スタジオプロダクション |
client.shots | 共有リンクの背後にある共有ショットレコード | スタジオプロダクション |
client.recast | Recast の実行と、自分で書いたスクリプト | Recast |
client.videoRemake | 短い動画の人物、ペット、商品、場所を置き換えます。Nodaro Cloud のみ | Video Remake |
client.trends | 既製の Video Remake のレシピを、自分の写真で実行します。Nodaro Cloud のみ | Trends |
client.pipelines | ストーリーから動画へのパイプライン | パイプライン |
client.copilot | Nodaro アプリ内限定の 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)| フィールド | 型 | 説明 |
|---|---|---|
id | string | Nodaro のユーザー ID です。 |
email | string | ユーザーのメールアドレスです。 |
displayName | string | null | 表示名です。設定されていない場合は null です。 |
avatarUrl | string | null | アバターの URL です。設定されていない場合は null です。 |
tier | string | 保存されているサブスクリプションのティアで、"free" や "pro" などです。実際に適用されるティア(従量課金を含む)については、client.credits.balance() の effectiveTier を読み取ってください。 |
isAdmin | boolean | ユーザーが管理者かどうかです。表示内容を決めるためだけに使ってください。権限のチェックは、サーバー自身がすべて行います。 |
組織機能のある 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? }]| フィールド | 型 | 説明 |
|---|---|---|
authorizationId | string | 許可です。revokeConnectedApp() に渡します。 |
name | string | null | アプリの名前です。自分自身を登録した MCP クライアントは、自分で名前を選んでいます。 |
kind | DeveloperAppKind | user(開発者アプリ)、first_party_mcp、dynamic_mcp(自分自身を登録した MCP クライアント)、community_instance(セルフホスティングのインストール)のいずれかです。 |
homepageUrl | string | null | アプリのホームページです。アプリが指定した場合だけ入ります。 |
scopes | DeveloperAppScope[] | 許可が持つスコープです。 |
connectedAt | string | ユーザーがアクセスを許可した日時で、ISO 8601 形式です。 |
lastUsedAt | string | 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/settings | UserSettings を返します:{ 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/availability | SurfaceAvailability を返します:{ 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): NodaroClientworkspaceId で動作する新しいクライアントを返します。新しいクライアントは、元のクライアントの認証、ベース 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) を使います。ほかのリソースメソッドと同じ認証ヘッダーを送り、同じタイムアウトを適用し、同じ型付きエラーをスローします。
関連ページ
TypeScript SDK
認証
エラー
組織とワークスペース
型
最終更新