プリセット
REST でノードプリセットの作成、更新、インポート、並べ替え、削除を行い、見本画像付きの公開された標準カタログを読み取り、プリセットのお気に入りを管理します。
プリセット API は、自分のノードプリセット、そのフォルダー、お気に入りの読み取りと書き込みを行い、各ノードタイプの標準プリセットカタログを読み取ります。プリセットとは、モデル、プロンプト、アスペクト比、品質など、ノードの設定に名前を付けて保存したもので、1 つの操作でノードに適用できます。プリセットの data は、保存されたノードの設定です。適用するには、それをノードの data にマージします。
ルートは、どのエディションでも使えます。ベアラートークンが必要です。個人用 API トークン(ndr_…)、OAuth アプリのトークン、またはセッショントークンです。OAuth アプリのトークンでは、読み取りに presets:read が、書き込みに assets:write が必要です。標準カタログ(GET /v1/node-presets/factory)には、トークンはまったく不要です。一部のワークフローに制限された個人用トークンは、自分のプリセットを使えません(403 forbidden)が、カタログはほかの誰とも同じように読み取れます。認証を参照してください。エディターでのプリセットの働きについては、プリセットを参照してください。
エンドポイント
| メソッド | パス | 説明 |
|---|---|---|
GET | /v1/node-presets | 自分のカスタムプリセットを、新しい順に返します。nodeType で絞り込めます(任意)。 |
GET | /v1/node-presets/factory | 1 つのノードタイプの標準プリセットカタログを返します。nodeType は必須です。トークンは不要です。 |
GET | /v1/node-presets/factory/groups | 1 つのノードタイプの標準カタログのカテゴリーを、プリセットなしで返します。nodeType は必須です。トークンは不要です。 |
GET | /v1/node-presets/favorites | 1 つのノードタイプについて、お気に入りに登録したプリセットの id を返します。nodeType は必須です。 |
GET | /v1/node-preset-groups | 自分のプリセットフォルダーとセクションを返します。nodeType で絞り込めます(任意)。 |
POST | /v1/node-presets | プリセットを作成します。 |
PATCH | /v1/node-presets/:id | プリセットの名前の変更、データの置き換え、移動、画像の設定を行います。 |
DELETE | /v1/node-presets/:id | プリセットと、そのお気に入りのエントリーを削除します。 |
POST | /v1/node-presets/import | 最大 500 件のプリセットを一度に作成します。 |
POST | /v1/node-presets/reorder | 位置を設定し、プリセットをフォルダー間で移動します。 |
POST | /v1/node-presets/favorites | プリセットをお気に入りに登録します。 |
DELETE | /v1/node-presets/favorites | お気に入りの登録を解除します。 |
POST | /v1/node-preset-groups | フォルダーまたはセクションを作成します。 |
PATCH | /v1/node-preset-groups/:id | フォルダーの名前の変更または移動を行います。 |
DELETE | /v1/node-preset-groups/:id | フォルダーを削除します。そのプリセットはフォルダーの外に移され、削除されるものはありません。 |
自分のプリセットを読み取る
GET /v1/node-presets は、{ data: NodePreset[] } を新しい順に返します。generate-image のような nodeType を渡すと、1 つのノードタイプのプリセットを一覧取得できます。
curl "https://app.nodaro.ai/v1/node-presets?nodeType=generate-image" \
-H "Authorization: Bearer $NODARO_API_KEY"import { createClient, StaticTokenAuth } from '@nodaro/sdk'
const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})
const presets = await client.presets.list('generate-image')
const cinematic = presets.find((p) => p.name === 'Cinematic Portrait')
const groups = await client.presets.listGroups('generate-image'){
"data": [
{
"id": "7e2c4a9f-1b3d-4f6a-8c5e-2d9b7a1f3c4e",
"nodeType": "generate-image",
"name": "Cinematic Portrait",
"description": "Warm key light, shallow depth of field",
"data": {
"provider": "nano-banana-pro",
"aspectRatio": "3:4",
"resolution": "2K",
"prompt": "cinematic portrait, warm key light, 85mm, shallow depth of field"
},
"groupId": null,
"tags": ["portrait"],
"sortOrder": 0,
"minReferences": 0,
"needsImage": false,
"previewUrl": null,
"createdAt": "2026-09-14T08:12:40Z",
"updatedAt": "2026-09-14T08:12:40Z"
}
]
}| フィールド | 意味 |
|---|---|
id | プリセットの uuid です。 |
nodeType | プリセットが属するノードタイプです。 |
name、description | プリセットの名前と、任意の説明です。 |
data | 保存されたノードの設定です。これが、実際に適用される内容です。 |
groupId | プリセットが入っているフォルダー(GET /v1/node-preset-groups で取得できるもの)、または null です。 |
tags、sortOrder | 自分で付けたタグと、リスト内でのプリセットの位置です。 |
minReferences | プリセットが使う、接続されたリファレンス画像の枚数です。0 は、使わないことを示します。 |
needsImage | minReferences が 1 以上のとき true です。 |
previewUrl | プリセットに設定した見本画像の、プリセット自身のコピーです。なければ null です。 |
createdAt、updatedAt | タイムスタンプです。書き込みでは、updatedAt を expectedUpdatedAt として送り返します。 |
プリセットが使う写真
minReferences が 0 より大きいプリセットは、その枚数のリファレンス画像を付けて実行してください。画像がないと、プリセットのプロンプトは存在しない写真を説明することになります。POST /v1/generate-image で presetId を使う場合は、画像を referenceImageUrls として送ります。
リファレンスシート、キャストと一貫性、名前で編集、顔のプライバシー、編集、ポートレート変身、スタイライズした被写体のプリセットには 1 枚の画像が、キャストメガグリッドには 2 枚の画像が必要です。プロンプトで {image:N} トークンを使うテンプレートも同様で、必要な枚数は N の最大値です。自分のプリセットも同じ方法で、プロンプト、その前後のテキスト、ネガティブプロンプトにある {image:N} と {image:N:label} のトークンから数えられます。
標準プリセットカタログを読み取る
GET /v1/node-presets/factory?nodeType=generate-image は、{ data: [...] } を返します。そのノードタイプ用に、Nodaro に最初から含まれているプリセットです。各エントリーは { id, name, description?, group?, groupKind?, section?, platforms?, data, minReferences, needsImage, previewUrl, previewSrcSet?, previewWidth?, previewHeight? } です。標準プリセットの id は <node-type>/<name> の形式で、たとえば generate-image/character-board や generate-video/orbit-360 です。
カタログにはトークンが不要です。誰に対しても同じで、ユーザーのデータを含まないので、クライアントアプリはログインしていない訪問者にもカタログを表示し、生成するときにだけログインを求められます。レスポンスは Cache-Control: public, max-age=300 付きで送られ、リクエストに付けた無効なトークンや期限切れのトークンは無視されます。
標準プリセットの previewUrl は、リクエストを送ったサーバー上の見本画像で、https://<host>/preset-previews/<nodeType>/<slug>.<hash>.webp の形式です。プリセットに画像がない間は null です。ファイル名は画像が変わるたびに変わるので、URL は無期限にキャッシュできます。
デプロイメントが独自に提供するプリセットには、デプロイメントが指定した画像が付きます。これは絶対 URL か、デプロイメントがサイト上に置いたファイルを指す、/brand/presets/harbor.webp のようなサイト上のパスです。REST ルート、/factory、および /factory/groups の previewUrl と previewUrls は、そのパスをそのまま返します。そのサイトが配信するページでは、パスをそのまま使います。それ以外のクライアントは、API を呼び出したアドレスを基準にパスを解決します。MCP ツールは、絶対 URL として返します。
# The presets that need a photo, and their example pictures. No token needed.
curl -s "https://app.nodaro.ai/v1/node-presets/factory?nodeType=generate-image" \
| jq '.data[] | select(.needsImage) | {id, minReferences, previewUrl}'const { data } = await client.presets.listFactory('generate-video')
const orbit = data.find((p) => p.id === 'generate-video/orbit-360')標準プリセットの分類
groupはフォルダーです。たとえば、"YouTube"、"Shorts · TikTok"、"Social & Ads"、"Business"、"Life & Events"、"Layout"、"Text"などです。sectionは、ある場合、グループ内の小見出しです。たとえば、"Finance & Crypto"のような YouTube のトピックや、"Instagram feed"です。platformsは、ある場合、結果の投稿先を合う順に並べたものです。たとえば、["TikTok", "Reels", "Shorts"]、["LinkedIn"]、["Print", "Etsy"]です。
ルック、レイアウト、スタジオのフォルダーなど、小見出しや投稿先のないプリセットでは、そのフィールドは含まれません。section と platforms でグループ化や絞り込みをするのは、フィールドがある場合だけにしてください。
カテゴリーだけを一覧表示する
GET /v1/node-presets/factory/groups?nodeType=generate-image は、標準カタログのカテゴリーを、プリセットなしで返します。応答は数 KB で、カテゴリーを一覧表示するメニューや棚に向いています。トークンは不要です。応答は { data: [{ group, shelf, count, previewUrl, previewUrls }] } です:
| フィールド | 内容 |
|---|---|
group | カテゴリーの名前で、プリセットの group と同じです。 |
shelf | ピッカーがカテゴリーを分類する棚です。video、marketing、photos、creative、life、pro、またはまだどの棚にも指定されていないカテゴリーの場合は more です。 |
count | カテゴリーに含まれるプリセットの数です。 |
previewUrl | カテゴリーの中で見本画像を持つ最初のプリセットの見本画像、または null です。 |
previewUrls | カテゴリーの最初の見本画像 3 枚です。カタログ順で、同じ画像は一度だけです。見本画像を持つプリセットがなければ空です。 |
カテゴリーは、ピッカーが表示する順に並びます。棚ごとに並び、各棚の中では、その棚が名前で指定したカテゴリーが設計どおりの順に先に来て、残りがカタログの順で続きます。
画像のサイズ
標準プリセットの画像には 2 つのサイズがあります。previewUrl のタイル用の画像は幅 512 px で、全画面用の画像は最大で幅 1024 px です。全画面用の画像は /preset-previews/1024/… にあります。previewSrcSet は、両方の画像を実際の幅とともに示します。そのまま <img srcset> に使えるため、ブラウザーが表示できる幅に合わせて画像を選びます。
<img src="{previewUrl}" srcset="{previewSrcSet}" sizes="(min-width: 900px) 80vw, 100vw" alt="{name}">previewSrcSet は、両方のファイルがあるプリセットにだけ含まれ、自分のプリセットには含まれません。MCP の一覧には含まれません。
previewWidth と previewHeight は、タイル画像の実際の幅と高さです。読み込む前に、各画像をその形の枠で描くのに使えます。プリセットの data.aspectRatio は生成するものの形で、画像の形と同じとは限りません。画像のある標準プリセットに含まれ、自分のプリセットには含まれません。
プリセットを適用する
プリセットで 1 枚の画像を生成するには、POST /v1/generate-image でその id を presetId として送ります。サーバーは、エディターが画像生成ノードに適用するのと同じ方法でプリセットを適用し、送ったフィールドがそれより優先されます。画像生成でプリセットを適用するを参照してください。
ワークフローでプリセットを適用するには、ワークフローを作成または更新するときに、その data をノードの data にマージします。マージした後にノードで設定した値が優先されます。
const node = {
id: 'portrait-1',
type: 'generate-image',
data: { ...cinematic.data, prompt: 'a lighthouse keeper at dawn' },
}プリセットには、promptPrefix と promptSuffix を持たせることもできます。ノードの実行時に、プロンプトの前後に追加されるテキストです。プロンプトの前後のテキストを参照してください。
MCP では、list_node_presets でプリセットを探し、get_node_preset で読み取るか、presetId を generate_image などの生成ツールに直接渡します。サーバー側でプリセットが適用され、プロンプトはプリセットの前後のテキストで囲まれ、明示的に渡したフィールドがあれば、それが優先されます。MCP ツールリファレンスを参照してください。
お気に入り
お気に入りに登録すると、そのプリセットがエディターのプリセット一覧の先頭に表示されます。お気に入りの id は、標準プリセットの id か、カスタムプリセットの uuid のいずれかです。OAuth アプリのトークンでは、読み取りに presets:read が、書き込みに assets:write が必要です。
| メソッド | パス | クエリまたはボディ | 戻り値 |
|---|---|---|---|
GET | /v1/node-presets/favorites | nodeType(必須) | { data: string[] }。新しい順です。 |
POST | /v1/node-presets/favorites | ボディ { nodeType, presetId } | { data: { success: true } }。すでにお気に入りのプリセットを追加しても、何も変わりません。 |
DELETE | /v1/node-presets/favorites | nodeType と presetId(どちらも必須) | { data: { success: true } }。すでに解除したお気に入りを解除しても、何も変わりません。 |
標準プリセットの id には / が含まれるため、DELETE のクエリ文字列では presetId を URL エンコードしてください。
curl -X DELETE "https://app.nodaro.ai/v1/node-presets/favorites?nodeType=generate-image&presetId=generate-image%2Fcharacter-board" \
-H "Authorization: Bearer $NODARO_API_KEY"プリセットの作成と編集
| メソッド | パス | ボディまたはクエリ | 内容 |
|---|---|---|---|
POST | /v1/node-presets | { nodeType, name, description?, data, groupId?, tags?, sortOrder?, previewUrl? } | プリセットを作成します。プリセットとともに 201 を返します。 |
PATCH | /v1/node-presets/:id | name、description、data、groupId、tags、sortOrder、previewUrl のいずれかと、任意の expectedUpdatedAt | 送ったフィールドを更新します。previewUrl: null で画像を削除します。 |
DELETE | /v1/node-presets/:id | 任意のクエリパラメーター expectedUpdatedAt | プリセットと、そのお気に入りのエントリーを削除します。 |
POST | /v1/node-presets/import | { presets: [{ nodeType, name, description?, data, previewUrl? }] }、最大 500 件 | 多数を一度に作成します。{ data: { imported } } を返します。 |
POST | /v1/node-presets/reorder | { groups?: [{ id, sortOrder }], presets?: [{ id, groupId?, sortOrder }] } | 位置を設定し、プリセットをフォルダー間で移動します。{ data: { ok: true } } を返します。 |
POST | /v1/node-preset-groups | { nodeType, name, kind?, sortOrder? } | folder(デフォルト。折りたためます)または section(平らな見出し)を作成します。 |
PATCH | /v1/node-preset-groups/:id | { name?, sortOrder? } | フォルダーの名前の変更または移動を行います。 |
DELETE | /v1/node-preset-groups/:id | なし | フォルダーを削除します。そのプリセットはフォルダーの外に移されます。 |
# Save a preset of your own, with one of your images as its picture
curl -s -X POST "https://app.nodaro.ai/v1/node-presets" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"nodeType": "generate-image", "name": "Studio portrait", "data": {"provider": "gpt-image-2", "aspectRatio": "3:4", "prompt": "{image:1:person}, studio portrait, soft key light"}, "previewUrl": "https://cdn.nodaro.ai/images/<jobId>.png"}'
# Rename it, refusing if it changed since you read it
curl -s -X PATCH "https://app.nodaro.ai/v1/node-presets/<presetId>" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Studio portrait (warm)", "expectedUpdatedAt": "<updatedAt>"}'const preset = await client.presets.create({
nodeType: 'generate-image',
name: 'Studio portrait',
data: { provider: 'gpt-image-2', aspectRatio: '3:4', prompt: '{image:1:person}, studio portrait' },
})
preset.needsImage // true: the prompt names {image:1}
await client.presets.addFavorite({ nodeType: 'generate-image', presetId: preset.id })CLI にも同じ書き込みがあります。nodaro presets create、update、delete、import、export、favorites、favorite、unfavorite と、create、update、delete を持つ nodaro presets groups です。MCP では、save_node_preset、delete_node_preset、favorite_node_preset でプリセットを管理します。
書き込みのルール
- 名前は、ノードタイプごとに一意です。大文字と小文字は区別されません。作成と更新では
409 name_takenが返されます。インポートでは両方のプリセットが残り、新しいほうに「… (imported 2)」(インポート 2)という名前が付きます。 dataは最大 64 KB です。結果、ジョブ ID、ノードのラベルなど、実行時のキーは取り除かれます。何も残らなかったインポートのプリセットは、読み飛ばされます。groupIdは、自分のフォルダーの 1 つである必要があります。そうでない場合、書き込みには400 invalid_groupが返されます。previewUrlは、Nodaro 上の自分の画像である必要があります。アップロードか、完了した生成の結果で、png、jpg、webp、gif、avif のいずれかです。ファイルがすでに存在している必要があるので、画像を作るジョブが完了してから設定してください。それ以外には、フィールドを示す400 validation_errorが返されます。たとえばインポートではpresets[3].previewUrlです。- プリセットは、画像の独自のコピーを持ちます。レスポンスの
previewUrlは、送ったアドレスではなくコピーのアドレスなので、ライブラリから元の画像を削除しても、プリセットが壊れることはありません。 expectedUpdatedAtを指定すると、読み取った後にプリセットが変更されていた場合、更新や削除に409 conflictが返されます。再試行する前に、もう一度読み取ってください。- 自分のものではないプリセットやフォルダー、または uuid ではない id には、
404 not_foundが返されます。 - 各アカウントが持てるのは、最大 5,000 件のプリセット、500 個のフォルダー、2,000 件のお気に入りです。それを超えると、作成、インポート、お気に入りの登録に
409 limit_reachedが返され、何も書き込まれません。全体が収まらないインポートは、1 件もインポートしません。 - API キーや OAuth アプリからの 1 回の並べ替えで移動できるのは、最大 500 件のプリセットと 100 個のフォルダーです。それを超えると
400 validation_errorが返されます。残りは別の呼び出しで送ってください。 - 書き込みは、認証情報ごとに 1 分あたり 60 回まで、インポートは 1 分あたり 10 回までです。それを超えると、ルートは
429 rate_limit_exceededを返します。
Recast のレンダリングプリセット
同じライブラリは、recast-render という名前空間の下に、Recast の生成設定を保存します。これはノードタイプではありません。Recast のレンダリング設定一式を保存し、再利用できるようにするものです。標準のエントリーは読み取り専用で、自分のエントリーは、どのデバイスでも自分だけの非公開のままです。
recast-render プリセットの data は、厳密で完全なスナップショットです。
{
"schemaVersion": 1,
"provider": "seedance-2-5",
"resolution": "480p",
"segmentSec": "max",
"renderMethod": "extend",
"anchorMode": "upfront",
"citeStyle": "bare",
"promptTiming": true,
"textOnly": false,
"interactive": true,
"anchorGates": false,
"musicGates": true,
"musicSource": "generated"
}| フィールド | 使える値 |
|---|---|
segmentSec | max、scenes-max(長め)、scenes(短め)のいずれかです。 |
resolution | 480p、720p、1080p、4k のいずれかです。 |
renderMethod | extend または keyframes です。 |
anchorMode | upfront、progressive、none のいずれかです。 |
citeStyle | bare または rich です。 |
musicSource | generated、original、upload のいずれかです。 |
promptTiming、textOnly、interactive、anchorGates、musicGates | true または false です。 |
ほかのプリセットと同じルートで書き込みます。写真は不要で、画像も持ちません(minReferences: 0、previewUrl: null)。不明なフィールドや不明なスキーマバージョンは、作成、更新、インポートで拒否されます。スナップショットには、ソースメディア、キャストのリファレンス、プロンプト、アップロードしたトラック、権利の確認、結果は一切含まれません。プリセットを適用すると設定が変わり、料金の見積もりが更新されますが、生成が始まることはありません。音楽の選択で original または upload を選んだ場合は、対象のプロジェクト自身のメディアが使われます。生成する前に、選んだモデルの現在の対応状況を確認してください。
エラー
| ステータス | コード | 意味 |
|---|---|---|
400 | validation_error | 必須の nodeType が指定されていないか、フィールドが無効です。 |
400 | invalid_group | groupId が、自分のフォルダーではありません。 |
401 | unauthorized | トークンがないか、無効か、取り消されています。 |
403 | forbidden | 一部のワークフローに制限された個人用トークンで、自分のプリセットを求めました。 |
403 | insufficient_scope | OAuth アプリのトークンに、読み取りの場合は presets:read が、書き込みの場合は assets:write がありません。 |
404 | not_found | プリセットやフォルダーが自分のものではないか、id が uuid ではありません。 |
409 | name_taken | このノードタイプに、その名前のプリセットがすでにあります。 |
409 | conflict | expectedUpdatedAt より後に、プリセットが変更されています。もう一度読み取ってください。 |
409 | limit_reached | アカウントが、プリセット、フォルダー、お気に入りの上限に達しています。 |
429 | rate_limit_exceeded | 1 分あたり 60 回を超える書き込み、または 1 分あたり 10 回を超えるインポートです。 |
よくある質問
API トークンで、プリセットを作成したり編集したりできますか?
はい。個人用 API トークン、または assets:write スコープを持つ OAuth アプリのトークンで、プリセットの作成、更新、削除、インポート、並べ替えと、フォルダーとお気に入りの管理ができます。
標準プリセットカタログを読み取るのに、トークンは必要ですか?
いいえ。GET /v1/node-presets/factory は公開されています。ユーザーのデータを含まないので、アプリはログインしていない訪問者にも、見本画像付きのカタログを表示できます。
コードからプリセットを適用するには、どうすればよいですか?
POST /v1/generate-image で presetId を送ると、サーバーがエディターと同じ方法でプリセットを適用します。ワークフローでは、プリセットの data オブジェクトをノードの data にマージします。
プリセットの minReferences は、何を意味しますか?
minReferences は、プリセットが使う接続されたリファレンス画像の枚数で、その数が 1 以上のとき needsImage は true です。そのようなプリセットは、その枚数のリファレンス画像を付けて実行してください。
プリセットのルートには、どの OAuth スコープが必要ですか?
自分のプリセットの読み取りには presets:read が、書き込みには assets:write が必要です。標準カタログには、スコープは不要です。個人用 API トークンとセッショントークンには、スコープは必要ありません。
関連ページ
プリセット
プロンプトの前後のテキスト
ノード
Recast
MCP ツールリファレンス
最終更新