**Cost**: 13 credits per successful call.

Image Layering supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/image/layering' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Decompose a single image into an **ordered stack of editable layers** — background, subject(s), and overlays — each rendered separately. The output is a JSON DSL describing the layer tree plus the per-layer image data. Use this when you want a designer-style PSD-equivalent, not a single flat composition.

## What this API is for

Turning a flat marketing image back into editable components; pre-processing for downstream compositing; setting up animated reveals where each layer animates separately; segmenting photo content for fine-grained editing.

Different from `image_to_design`: that one returns a structural design-tree (Body / Layer / Text / Image nodes with positions and styles). `image_layering` returns visual layers (independent rendered images that you can stack). They complement each other.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to decompose. |

No `model` parameter — uses Codia's layering pipeline.

## Response

Unique to this endpoint:

| Field | Type | Meaning |
|---|---|---|
| `data.type` | integer | Result-type code. Identifies the schema variant of `dsl`. |
| `data.dsl` | string | **JSON-encoded** layer tree. Parse client-side. Contains layer metadata + URLs to the rendered layer images. |

```json
{ "code": 0, "message": "ok", "data": { "type": 1, "dsl": "{\"layers\":[…]}" } }
```

The `dsl` field is intentionally a string (not a nested object) so you can store it verbatim or stream it without re-encoding.

## Billing & limits

- 13 credits per request from the unified Codia Open API balance.
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_layering` instead. Inputs and credit cost are identical.

任意のユーザー指定キー（最大 255 文字）。設定すると、成功した（2xx）レスポンスが 7 日間キャッシュされます。同じキーかつ同一のリクエストボディでリトライすると、キャッシュされたレスポンスが返されます（追加のクレジットは消費されません）。同じキーで異なるボディを送ると 409 が返されます。ネットワーク障害時に POST を安全にリトライできるようにするために使用します。multipart/form-data のアップロードでは、フォームフィールドとファイル内容でリクエストを比較するため、クライアントが新しい multipart boundary を選んでも、リトライしたアップロードにもキャッシュ済みのレスポンスが返されます。

Idempotency-Key

レイヤーに分解する画像の公開 URL

image_url

image

互換性のための元画像ファイルフィールド（非推奨: 代わりに `image` を使用してください）。

file

画像をアップロードしない場合の元画像 URL

code

message

type

JSON エンコードされた編集可能なレイヤーツリー

data

リクエストボディの形式が正しくないか、必須パラメータが不足しています

API キーが指定されていないか、無効か、失効しています

アカウントの残高が不足しているか、サブスクリプションの有効期限が切れています

アカウントにこのエンドポイントへのアクセス権がありません

Idempotency-Key が異なるリクエストボディで再利用されました。

レート制限に達しました。`Retry-After` ヘッダーに示された秒数だけ待ってからリトライしてください。

サーバーで予期しないエラーが発生しました

Image

LAUNCH OFFER

SHOP NOW

skin tone.

Vitamin C + hyaluronic acid for a bright

Vitamin C + hyaluronic acid for a brighter, even

Glow Serum

SKINCARE · NEW

VELORA

1 枚の画像を、個別に編集できる順序付きのレイヤー（背景、被写体、テキスト、オーバーレイ）に分解します。

画像レイヤー分割

入力

出力

関連する API