**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

평면 이미지를 개별적으로 편집할 수 있는 순서 있는 레이어 스택(배경, 피사체, 텍스트, 오버레이)으로 분리합니다.

이미지 레이어 분리

입력

출력

관련 API