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

Kunci opsional dari pengguna (maksimal 255 karakter). Jika diisi, respons sukses (2xx) di-cache selama 7 hari. Retry dengan kunci yang sama + body permintaan yang identik mengembalikan respons dari cache (tanpa potongan kredit tambahan); retry dengan kunci yang sama tetapi body berbeda mengembalikan 409. Gunakan agar POST aman di-retry saat terjadi gangguan jaringan. Untuk unggahan multipart/form-data, permintaan dibandingkan berdasarkan field formulir dan isi file, sehingga unggahan yang di-retry tetap diputar ulang meskipun klien memilih multipart boundary baru.

Idempotency-Key

URL publik gambar yang akan dipecah menjadi layer

image_url

image

Field file gambar sumber untuk kompatibilitas (usang: gunakan `image`).

file

URL gambar sumber jika tidak mengunggah gambar

code

message

type

Pohon layer yang dapat diedit, berenkode JSON

data

Body permintaan tidak valid atau parameter wajib tidak ada

API key tidak ada, tidak valid, atau sudah dicabut

Saldo akun tidak mencukupi atau langganan telah berakhir

Akun tidak memiliki akses ke endpoint ini

Idempotency-Key dipakai ulang dengan body permintaan yang berbeda.

Terkena rate limit. Tunggu selama jumlah detik di header `Retry-After` sebelum mencoba lagi.

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

Memecah gambar datar menjadi tumpukan layer berurutan (latar belakang, subjek, teks, dan overlay) yang dapat diedit secara terpisah.

Pemisahan Layer Gambar

Input

Output

API terkait