# プリセット

> 保存したノードプリセット、プリセットフォルダー、標準プリセットカタログを REST で読み取り、ノードにプリセットを適用して、お気に入りを管理します。

Source: https://nodaro.ai/ja/docs/developers/api/presets

**プリセット API** は、エディターで保存したノードプリセットと、各ノードタイプの標準プリセットカタログを読み取ります。プリセットとは、モデル、プロンプト、アスペクト比、品質など、ノードの設定に名前を付けて保存したもので、1 つの操作でノードに適用できます。API トークンに対しては、ルートは読み取り専用です。プリセットの作成と編集は、エディターで行います。

ルートは、どのエディションでも使えます。ベアラートークンが必要です。個人用 API トークン（`ndr_…`）、`presets:read` スコープを持つ OAuth アプリのトークン、またはセッショントークンです。[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。エディターでのプリセットの働きについては、[プリセット](https://nodaro.ai/docs/concepts/presets)を参照してください。

## エンドポイント
| メソッド | パス | 説明 |
| --- | --- | --- |
| `GET` | `/v1/node-presets` | 自分のカスタムプリセットを、新しい順に返します。`nodeType` で絞り込めます（任意）。 |
| `GET` | `/v1/node-preset-groups` | 自分のプリセットフォルダーとセクションを返します。`nodeType` で絞り込めます（任意）。 |
| `GET` | `/v1/node-presets/factory` | 1 つのノードタイプの標準プリセットカタログを返します。`nodeType` は必須です。 |
| `GET` | `/v1/node-presets/favorites` | 1 つのノードタイプについて、お気に入りに登録したプリセットの id を返します。`nodeType` は必須です。 |
| `POST` | `/v1/node-presets/favorites` | プリセットをお気に入りに登録します。ブラウザーのセッションでのみ使えます。 |
| `DELETE` | `/v1/node-presets/favorites` | お気に入りの登録を解除します。ブラウザーのセッションでのみ使えます。 |

## 自分のプリセットを読み取る
`GET /v1/node-presets` は、`{ data: NodePreset[] }` を新しい順に返します。`generate-image` のような `nodeType` を渡すと、1 つのノードタイプのプリセットを一覧取得できます。

**curl**

```bash
curl "https://app.nodaro.ai/v1/node-presets?nodeType=generate-image" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts

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')
```

```json
{
"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,
"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` | 自分で付けたタグと、リスト内でのプリセットの位置です。 |
| `createdAt`、`updatedAt` | タイムスタンプです。 |

## 標準プリセットカタログを読み取る
`GET /v1/node-presets/factory?nodeType=generate-image` は、`{ data: FactoryPreset[] }` を返します。そのノードタイプ用に、Nodaro に最初から含まれているプリセットです。各エントリーは `{ id, name, description?, group?, groupKind?, data }` です。標準プリセットの id は `<node-type>/<name>` の形式で、たとえば `generate-image/character-board` や `generate-video/orbit-360` です。

**curl**

```bash
curl "https://app.nodaro.ai/v1/node-presets/factory?nodeType=generate-video" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts
const { data } = await client.presets.listFactory('generate-video')
const orbit = data.find((p) => p.id === 'generate-video/orbit-360')
```

## プリセットを適用する
プリセットの `data` は、保存されたノードの設定です。プリセットを適用するには、ワークフローを作成または更新するときに、その `data` をノードの data にマージします。マージした後にノードで設定した値が優先されます。

```ts
const node = {
id: 'portrait-1',
type: 'generate-image',
data: { ...cinematic.data, prompt: 'a lighthouse keeper at dawn' },
}
```

プリセットには、`promptPrefix` と `promptSuffix` を持たせることもできます。ノードの実行時に、プロンプトの前後に追加されるテキストです。[プロンプトの前後のテキスト](https://nodaro.ai/docs/concepts/prompt-pre-post-text)を参照してください。

MCP では、`list_node_presets` でプリセットを探し、`get_node_preset` で読み取るか、`presetId` を `generate_image` などの生成ツールに直接渡します。サーバー側でプリセットが適用され、プロンプトはプリセットの前後のテキストで囲まれ、明示的に渡したフィールドがあれば、それが優先されます。[MCP ツールリファレンス](https://nodaro.ai/docs/mcp/tools)を参照してください。

## お気に入り
お気に入りに登録すると、そのプリセットがエディターのプリセット一覧の先頭に表示されます。お気に入りの id は、標準プリセットの id か、カスタムプリセットの uuid のいずれかです。読み取りは、`presets:read` を持つ OAuth アプリのトークンを受け付けます。書き込みはブラウザーのセッションのみで、どの OAuth スコープでも許可されません。

| メソッド | パス | クエリまたはボディ | 戻り値 |
| --- | --- | --- | --- |
| `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 エンコードしてください。

```bash
curl -X DELETE "https://app.nodaro.ai/v1/node-presets/favorites?nodeType=generate-image&presetId=generate-image%2Fcharacter-board" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

## プリセットの作成と編集
プリセットの作成、名前の変更、削除は、Nodaro の Web アプリ自身のログイン中のセッションに限られます。`POST /v1/node-presets` はプリセットを作成し、`PATCH /v1/node-presets/:id` は名前の変更またはデータの置き換えを行い、`DELETE /v1/node-presets/:id` は削除します。API トークンまたは OAuth アプリのトークンでは `403 forbidden` が返されます。

これらの書き込みは、任意で `expectedUpdatedAt` を受け付けます。`PATCH` ではボディに、`DELETE` ではクエリパラメーターに指定します。プリセットライブラリが返したタイムスタンプを送信してください。それ以降にプリセットが変更されていた場合、ルートは `409 conflict` を返します。再試行する前に、もう一度読み取ってください。

### Recast のレンダリングプリセット
同じライブラリは、`recast-render` という名前空間の下に、Recast の生成設定を保存します。これはノードタイプではありません。[Recast](https://nodaro.ai/docs/developers/api/recast) のレンダリング設定一式を保存し、再利用できるようにするものです。標準のエントリーは読み取り専用で、自分のエントリーは、どのデバイスでも自分だけの非公開のままです。

`recast-render` プリセットの `data` は、厳密で完全なスナップショットです。

```json
{
"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` です。 |

不明なフィールドや不明なスキーマバージョンは拒否されます。スナップショットには、ソースメディア、キャストのリファレンス、プロンプト、アップロードしたトラック、権利の確認、結果は一切含まれません。プリセットを適用すると設定が変わり、料金の見積もりが更新されますが、生成が始まることはありません。音楽の選択で `original` または `upload` を選んだ場合は、対象のプロジェクト自身のメディアが使われます。生成する前に、選んだモデルの現在の対応状況を確認してください。

## エラー
| ステータス | コード | 意味 |
| --- | --- | --- |
| `400` | `validation_error` | 必須の `nodeType` が指定されていないか、フィールドが無効です。 |
| `401` | `unauthorized` | トークンがないか、無効か、取り消されています。 |
| `403` | `forbidden` | API トークンまたは OAuth アプリのトークンで書き込みが送られました。書き込みにはブラウザーのセッションが必要です。 |
| `403` | `insufficient_scope` | OAuth アプリのトークンに `presets:read` がありません。 |
| `409` | `conflict` | `expectedUpdatedAt` より後に、プリセットが変更されています。もう一度読み取ってください。 |

## Frequently asked questions

### API トークンで、プリセットを作成したり編集したりできますか？

いいえ。API では、API トークンと OAuth アプリのトークンに対して、プリセットは読み取り専用です。プリセットの作成、名前の変更、削除は、ブラウザーのセッションでログインしているエディターで行います。

### コードから、ノードにプリセットを適用するには、どうすればよいですか？

プリセットを読み取り、ワークフローを構築または更新するときに、その data オブジェクトをノードの data にマージします。MCP では、generate_image などの生成ツールに presetId を渡すと、サーバー側でプリセットが適用されます。

### カスタムプリセットと標準プリセットは、どう違いますか？

カスタムプリセットは、自分で保存したプリセットで、uuid で識別されます。標準プリセットは、ノードタイプの標準カタログの一部で、generate-image/character-board のような id で識別されます。

### プリセットのルートには、どの OAuth スコープが必要ですか？

OAuth アプリのトークンには presets:read が必要です。個人用 API トークンとセッショントークンには、スコープは必要ありません。プリセットの所有者は自分自身だからです。