---
title: "Layerize Image"
method: POST
path: "/media/layerize"
tags: ["media"]
---

# Layerize Image

`POST /media/layerize`

## Request

- Base URL: `https://api.moda.app/v1`
- URL: `https://api.moda.app/v1/media/layerize`
- Auth: HTTP bearer

Rebuild a flat image into editable layers on a new canvas (metered; async job).

Creates a canvas sized to the image with the image placed as a full-page
node, then starts the same hidden headless layerize job the in-app
"Layerize" action runs: an agent reconstructs the image's background,
objects, and text as separate editable nodes and merges the finished group
back over the placed image. The response returns immediately with a
``task_id`` and the created canvas — poll ``GET /v1/media/layerize/{task_id}``
(about every ``retry_after_ms``) until the status is terminal. The job
typically takes a few minutes; the canvas shows the flat image until the
merge lands.

Billing: metered as a normal agent run (model tokens plus per-call
provider usage inside the job) against team credits — there is no fixed
per-layerize price. The kickoff runs a credit precheck and returns the
typed 402 when the balance refuses.

## Headers

- `Moda-Version` '2026-04-12' | '2026-05-01'

## Request body

- LayerizeRequest
  - `image` string, required: The image to layerize: a file_ id from an upload or an http(s) image URL.
  - `variant` 'full' | 'text': 'full' rebuilds every layer (background, objects, text); 'text' extracts editable text only.
  - `canvas_name` string, nullable: Name for the created canvas. Defaults to 'Layerized image'.
  - `idempotency_key` string, nullable: A retried call with the same key replays the stored response (replayed:true) instead of paying for a second provider render.

## Response `200`

Successful Response

- object

## Other responses

- `401`: Authentication required.
- `402`: Insufficient credits for a metered operation.
- `403`: Permission denied for this scope.
- `404`: Resource not found.
- `409`: Conflict (idempotency / resource state).
- `422`: Request validation failed.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-11-03** `9ac6a3abc0f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/moda/apis/moda-public-api/changes/media/layerize/post.md)

---

[API](https://skmtc.dev/moda/apis/moda-public-api.md) - [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moda/apis/moda-public-api/revisions/9ac6a3abc0f8?raw)