# レイヤーに分割

> 1 枚の画像を、ベース画像と個別のレイヤーに分割します。各要素はそれぞれ透過 PNG になり、名前、位置ボックス、重なり順も一緒に返ります。

Source: https://nodaro.ai/ja/docs/nodes/image/split-into-layers

**レイヤーに分割**ノードは、1 枚の画像をベース画像と個別のレイヤーに分解します。人物、動物、商品、1 行のテキスト、ロゴなどの各要素が、それぞれ独立した透過 PNG として返ります。ノードはレイヤーデータも返し、各レイヤーが何で、どこにあり、どう重なるかを示します。

レイヤーを 1 枚ずつ編集したり、アニメーション化したり、差し替えたりしてから、元どおりに組み立てます。**分離する対象**を空欄のままにしてノードに主な要素を見つけさせるか、欲しい要素を説明します。

- Found in: Image › Edit & Retouch
- API type: `split-into-layers`

## 使いどころ
- 商品や見出しなど、画像の 1 つの要素だけを、ほかの部分に触れずに編集します。
- レイヤーを[**動画生成**](https://nodaro.ai/docs/nodes/video/generate-video)に接続して、各要素を個別にアニメーション化します。
- [**画像をアップスケール**](https://nodaro.ai/docs/nodes/image/upscale-image)で、すべての要素を個別にアップスケールします。
- 要素を移動、リサイズ、差し替えしてからベース画像の上に戻し、画像を組み立て直します。
- すべての要素を、デザインツールですぐに使える透過 PNG として取り出します。

## クイックスタート
### ノードを追加する
キャンバス上で Tab を押し、**画像 › 編集とレタッチ › レイヤーに分割**を選びます。

### 画像を接続する
[**画像アップロード**](https://nodaro.ai/docs/nodes/image/upload-image)や[**画像生成**](https://nodaro.ai/docs/nodes/image/generate-image)などの画像ノードを、**画像**入力に接続します。ノード上で画像をアップロードすることもできます。

### 設定を選ぶ
設定パネルを開きます。**最大レイヤー数**と**サイズ**を設定します。要素を自分で選ぶには、**分離する対象**にその要素を説明します。

### 実行する
ノードの**実行**をクリックします。1 回の実行には、通常 1 分もかかりません。ノードには、ベース画像と、レイヤーを名前付きで並べた列が表示されます。

Workflow: ポスターをレイヤーに分割し、個別モードの接続で各レイヤーを 1 枚ずつアップスケールします。

- 画像アップロード → レイヤーに分割 (画像)
- レイヤーに分割 → 画像をアップスケール (レイヤー)

## 入力
| 入力 | 受け付けるもの | 役割 |
| --- | --- | --- |
| **画像** | 画像アップロード、画像生成、**画像修正**などの画像ノード、またはキャラクター、オブジェクト、ロケーション | 分割する画像で、JPEG、PNG、WebP に対応します。サイズの大きいファイルや、HEIC、AVIF などのほかの形式は、先に変換されます。接続したキャラクター、オブジェクト、ロケーションは、画像として使われます。必須です。 |

## 出力
| 出力 | 渡すもの |
| --- | --- |
| **ベース** | ベース画像で、不透明な PNG です。 |
| **レイヤー** | すべてのレイヤーを下から上の順に並べたリストです。各レイヤーは、要素に合わせて切り抜いた透過 PNG です。 |
| **レイヤーデータ** | レイヤーごとに 1 件のエントリーで、**レイヤー**と同じ順に並びます。 |

**レイヤー**はリストです。そこからの接続がデフォルトの**個別**モードの場合、次のノードはレイヤーごとに 1 回ずつ実行されます。たとえば、画像をアップスケールに接続してすべてのレイヤーをアップスケールしたり、動画生成に接続して各レイヤーをアニメーション化したりします。接続を**一括**にすると、[**画像コラージュ**](https://nodaro.ai/docs/nodes/image/image-collage)や画像生成のリファレンスなど、複数の画像を受け取るノードに、すべてのレイヤーをまとめて渡せます。[リストとバッチ処理](https://nodaro.ai/docs/concepts/lists-and-batching)を参照してください。

ベース画像とすべてのレイヤーは、ライブラリにも保存されます。各レイヤーは、その名前で保存されます。

### レイヤーデータ
**レイヤーデータ**出力は次のようになります。

```json
[
{
"name": "Arctic fox",
"description": "The full body of the standing white arctic fox, with no background.",
"zIndex": 1,
"width": 1108,
"height": 946,
"box": { "x1": 228, "y1": 482, "x2": 897, "y2": 1070 },
"boxNormalized": { "x1": 223, "y1": 314, "x2": 875, "y2": 696 },
"url": "https://…/layer.png",
"baseUrl": "https://…/base.png"
}
]
```

| フィールド | 意味 |
| --- | --- |
| `zIndex` | 重なり順です。`1` はベース画像のすぐ上に置かれ、数字が大きいほど上に描かれます。 |
| `box` | ベース画像上でレイヤーが置かれる位置を、ベース画像のピクセルで示します。`x1` と `y1` は左上の角、`x2` と `y2` は右下の角です。 |
| `boxNormalized` | 同じボックスを、ベース画像の幅と高さを 0〜1000 とした値で示します。 |
| `width`、`height` | レイヤーのファイル自体のピクセル数です。レイヤーは、ベース画像の縮尺で切り抜かれるわけではありません。要素に合わせて切り抜かれ、要素自体の形のまま、**サイズ**設定のピクセル数の目安（1K で約 1 メガピクセル）で保存されます。レイヤーを元の位置に戻すには、その `box` に合わせて拡大縮小します。 |
| `name`、`description` | その要素が何かを示します。レイヤーによっては含まれないことがあります。 |
| `url` | レイヤーのファイルで、**レイヤー**の該当する項目と同じです。 |
| `baseUrl` | レイヤーの切り抜き元のベース画像で、**ベース**と同じです。 |

### 1 回の実行で複数の画像を処理する
**画像**に画像のリストを接続します。たとえば、画像リンクの[**リスト**](https://nodaro.ai/docs/nodes/automate/list)や、**個別**モードの接続で複数の画像を作るノードです。するとノードは、画像ごとに 1 回ずつ実行されます。各実行の結果はそれぞれ独立したテイクになり、その画像のベース、レイヤー、レイヤーデータを持ちます。

- **ベース**は、結果を出したすべての画像のベース画像を、画像が入ってきた順に並べます。実行が失敗した画像にはベースがないので、リストから除かれます。
- **レイヤー**は、すべての画像のレイヤーを、画像ごとに順に渡します。**個別**モードの接続では、すべての画像のレイヤーごとに次のノードが 1 回ずつ実行されます。最初の画像のレイヤー、次に 2 番目の画像のレイヤー、という順です。**一括**モードの接続はすべてをまとめて渡し、**選択中**モードの接続は最初のものを読み取り、**項目**モードの接続はリスト全体から 1 つを選びます。
- **レイヤーデータ**は、それらのレイヤーと 1 対 1 で対応します。各エントリーには `row` も含まれます。これは元になった入力画像の番号で、0 から数えます。レイヤーのない画像は、**レイヤー**にも**レイヤーデータ**にも何も加えません。実行が失敗した画像も同じです。各画像は自分の番号を保つので、`row` の番号は飛ぶことがあります。

レイヤーとそのベース画像を対応させるには、`row` ではなく `baseUrl` を使います。**ベース**には、結果を出した画像だけが並びます。ある画像が失敗すると、それより後の画像の `row` は、**ベース**の中の位置と一致しなくなります。次の例では、2 番目の画像が失敗しています。フクロウのベース画像は**ベース**の 2 番目の項目ですが、その `row` は 2 です。

```json
[
{ "name": "Fox", "zIndex": 1, "url": "https://…/fox.png", "baseUrl": "https://…/base-1.png", "row": 0 },
{ "name": "Owl", "zIndex": 1, "url": "https://…/owl.png", "baseUrl": "https://…/base-3.png", "row": 2 }
]
```

1 枚の画像での実行では、最初の例のように、レイヤーデータに `row` は含まれません。ノードには、表示中のテイクのレイヤーが表示されます。別のテイクを選ぶと、その画像のレイヤーが表示されます。**レイヤー**と**レイヤーデータ**からの接続は、どのテイクを選んでも、すべての画像のレイヤーを渡し続けます。同じように、**ベース**からの**個別**モードの接続も、すべての画像のベース画像を並べ続けます。最初の実行の前は、実行の見積もりで、**レイヤー**からの**個別**モードの接続を、画像ごとに**最大レイヤー数**として数えます。

## 設定
| 設定 | 役割 |
| --- | --- |
| **最大レイヤー数** | 1 回の実行で作るレイヤーの最大数で、1〜99 です。デフォルトは 9 です。ベース画像はこれとは別に付きます。要素がこの数より多い画像では、要素が省かれることはなく、まとめられるので、より少なく大きなレイヤーになります。 |
| **サイズ** | 各画像のピクセル数の目安で、`1K`（デフォルト）、`1.5K`、`2K` から選びます。**自動**は、画像本来のサイズを 1K〜2K の範囲で使います。 |
| **分離する対象** | 任意で、最大 2,000 文字です。どの要素を分離するかを、平易な言葉で説明します。空欄のままにすると、ノードが主な要素を自動で見つけます。 |

**分離する対象**では、`<bbox>x1 y1 x2 y2</bbox>` で要素の位置を示せます。数値は、画像全体を 0〜1000 とした角の座標です。例：

```text
Separate the title <bbox>179 58 809 197</bbox> and the parrot <bbox>330 274 641 991</bbox>
```

### 公開アプリで
このノードを含むワークフローで作った[アプリ](https://nodaro.ai/docs/concepts/apps)では、ユーザーが**最大レイヤー数**を 1〜20 のスライダーで、**サイズ**を**自動**、`1K`、`1.5K`、`2K` のいずれかで設定できるようにできます。アプリのスライダーと、ワークフローの実行での上書きは、これらの値に制限されます。それ以外の値は、実行が始まる前に拒否されます。

アプリは、ユーザーが変更した値だけを送ります。**最大レイヤー数**を変更しない実行では、作成者がノードに保存した値（最大 99 レイヤー）が使われ、その値の分が確保されます。たとえば、ノードに 50 レイヤーを保存した場合、51 枚の画像の分が確保されます。スライダーを最大にした場合、`2K` で 20 レイヤーなら 369 クレジットが確保されます。

## クレジット
1 回の実行では、返す可能性のある最大の画像数、つまり**最大レイヤー数**とベース画像の分が**確保**されます。**請求**されるのは、実際に返された画像、つまりベース画像と各レイヤーの分だけです。`1K` と `1.5K` は同じ料金で、`2K` と**自動**はそれより高くなります。**実行**ボタンには、選んだ設定で確保される額が表示されます。

| 例 | 確保 | 請求 |
| --- | --- | --- |
| デフォルト：1K で 9 レイヤー | 104 | — |
| 1K で 3 レイヤーを返した場合（4 枚） | | 44 |
| 2K または**自動**で 3 レイヤーを返した場合（4 枚） | | 74 |
| 1K で**最大レイヤー数**が 5 | 64 | — |
| 要素が見つからない場合：1K でベース画像のみ | | 15 |

- **要素が見つからない場合**：実行はベース画像だけで完了し、その 1 枚の分が請求されます。
- **保存できないレイヤーがある場合**：何度か試してもレイヤーを保存できない場合、実行はそのレイヤーなしで完了し、保存できた画像の分だけが請求されます。ノードには、「9 件中 2 件のレイヤーを保存できませんでした」のように、保存できなかったレイヤーの数が表示されます。
- **失敗した実行のクレジットは返還される**：ベース画像を保存できない実行も含まれます。

セルフホスティングの Community エディションと Business エディションでは、クレジットを使いません。

## ヒント
- **順番どおりに組み立て直す**：画像を作り直すには、各レイヤーをベース画像上のその `box` の位置に、`zIndex` の順に配置します。
- **まとめる度合いを選ぶ**：**最大レイヤー数**を小さくすると、見出し全体を 1 枚のレイヤーにするなど、要素がまとめられます。大きくすると、要素は分かれたままになります。
- **必要な要素を指定する**：主な要素が欲しいものと違う場合は、**分離する対象**に「the logo and the price tag」（ロゴと値札）のように説明します。

## トラブルシューティング
| 問題 | 対処 |
| --- | --- |
| 実行がベース画像だけを返した | ノードが要素を見つけられませんでした。**分離する対象**に欲しい要素を書くか、`<bbox>` で位置を指定してください。 |
| 2 つの要素が 1 つのレイヤーになった | 画像の要素が**最大レイヤー数**より多い状態です。**最大レイヤー数**を増やしてください。 |
| レイヤーがベース画像とずれる | レイヤーのファイルは、ベース画像と同じ縮尺ではありません。配置する前に、レイヤーデータの `box` に合わせて拡大縮小してください。 |
| 一部のレイヤーを保存できなかったと表示される | 実行はそのレイヤーを除いて完了し、保存した画像の分だけが請求されています。もう一度ノードを実行すると、そのレイヤーを得られます。 |

## API から
`POST /v1/split-into-layers` に `{ imageUrl, maxLayers?, size?, prompt?, sessionId?, origin? }` を渡すとジョブがキューに入り、その `jobId` が返ります。形式が正しくないリクエストは、クレジットが確保される前に `400 validation_error` を返します。`sessionId` はジョブをあなたのセッションの 1 つに入れ、`origin` はジョブにあなたのアプリのスラッグでタグを付けます。`Idempotency-Key` ヘッダーを付けると、再試行は 2 つ目のジョブを開始せず、最初のリクエストが開始したジョブを返します（`{ jobId, deduped: true }`）。

完了したジョブの `output_data.imageUrl` はベース画像で、`output_data.layers` はレイヤーのファイルを順に並べます。`output_data.layerData` は上記のレイヤーデータです。`output_data.layerCount` は保存できたレイヤーの数、`output_data.layersNotSaved` は保存できなかったレイヤーの数です（すべてのレイヤーを保存できた場合は `0`）。

実行前に確保額を知るには、同じ本文で `{ "type": "split-into-layers", "params": { … } }` を `POST /v1/quote` に送ります。何も開始されません。応答の `identifier` は確保に使われる料金（`split-into-layers:<1k|2k>:<images>`）で、`reserve` は確保されるクレジットです。1K で**最大レイヤー数**が 5 なら 64 クレジット、デフォルトなら 104 クレジットです。SDK では `client.nodes.quote("split-into-layers", body)` を呼び出します。ノードを実行できない場合、見積もりも実行と同じように `403 node_not_available` で拒否されます。

SDK のメソッドは `client.media.splitIntoLayers`、MCP ツールは `split_into_layers`、CLI コマンドは `nodaro media split-layers` です。[単一ノードの実行](https://nodaro.ai/docs/developers/api/nodes)、[ジョブ](https://nodaro.ai/docs/developers/api/jobs)、[SDK のメディアとアップロード](https://nodaro.ai/docs/developers/sdk/media-and-uploads)、[MCP ツール](https://nodaro.ai/docs/mcp/tools)を参照してください。

## よくある質問

### 「レイヤーに分割」ノードは何を返しますか？

要素の背後にあるシーンであるベース画像と、人物、商品、1 行のテキスト、ロゴなど、要素ごとに 1 枚の透過 PNG のレイヤーを返します。各レイヤーの名前、位置ボックス、重なり順を含むレイヤーデータも返します。

### プロンプトを書く必要はありますか？

いいえ。「分離する対象」を空欄のままにすると、ノードが主な要素を自動で見つけます。欲しい要素を説明するのは、主な要素が必要な要素と違う場合だけです。

### 1 回の実行で、いくつのレイヤーを作れますか？

「最大レイヤー数」の設定までで、1〜99 の範囲、デフォルトは 9 です。要素がそれより多い画像では、要素が省かれることはなく、まとめられるので、より少なく大きなレイヤーになります。

### 「レイヤーに分割」のクレジットはいくらですか？

1 回の実行では、最大レイヤー数とベース画像の分が確保され、実際に返された画像の分だけが請求されます。デフォルトの 1K で 9 レイヤーの場合、104 クレジットが確保されます。1K で 3 レイヤーを返した実行には、44 クレジットが請求されます。

### レイヤーを元どおりに組み立てるにはどうすればよいですか？

各レイヤーを、ベース画像上のそのボックスの位置に、zIndex の小さいものから大きいものの順に重ねます。レイヤーのファイルは要素に合わせて切り抜かれているので、先にそのボックスの大きさに拡大縮小してください。