> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Layerize images

> Get PNG layers and editable text metadata without creating a canvas.

Submit an image to `POST /v1/media/layerize-assets` to receive downloadable PNG
layers and JSON text details. Use normal [API-key authentication](/api-reference/authentication)
with `media:generate` and `tasks:read`. No feature flag, canvas-write scope, or export scope is required.

```bash theme={null}
curl https://api.moda.app/v1/media/layerize-assets \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/poster.png",
    "mode": "full",
    "idempotency_key": "poster-42"
  }'
```

`image` can also be a `file_...` reference from the upload API. `mode` is `full`
(the default) or `text`, which separates text while keeping other artwork together.
Unknown options are rejected; there are no prompt, seed, font override, or quality knobs.

## Wait for the result

The HTTP 202 response is a Task with `kind: "layerize_assets"`, an `id`, and
`links.self`. Poll that URL at `retry_after_ms` (normally 3 seconds). This task
kind always uses the canonical envelope, including under the default API version.
Keep the task ID: these asset tasks are not part of the canvas-design task list.
Only the submitting user with a key for the same team can poll or cancel it.

You can supply `callback_url` at submission to receive a signed terminal
[webhook](/api-reference/webhooks) instead. Polling and webhook data use the same result shape.
Cancellation uses `POST /v1/tasks/{id}/cancel` and requires `tasks:cancel`.
If cancellation cannot be signaled, it returns 503 with `Retry-After`; 202 means
the signal was sent but is not yet acknowledged.

If dispatch to the worker queue has an uncertain outcome after the task is
created, submission still returns HTTP 202 with that task's ID and polling link.
Poll that task rather than resubmitting; keyed retries return the same handle.

## Use the layers

On `status: "succeeded"`, `result.layers` contains one PNG per delivered layer,
including text layers. Each entry contains `file_id`, a downloadable `url`,
`kind`, `z_index`, `width`, `height`, `x`, and `y`.

All PNGs match the full image dimensions and sit at `(0, 0)`. Stack them in
ascending `z_index` using ordinary source-over alpha compositing. Text is linked
through `text` and `text_items`: content, bounds, transform, layout dimensions,
paragraph alignment, and span font/color/formatting details. Font files are not included.

Effects that cannot be separated faithfully may produce composite layers,
potentially a single full-image composite. These usable results have
`outcome: "partial"` and explicit warnings such as `layers_combined`; linked text
metadata remains available. No usable output means a failed task.

## Limits, billing, and storage

* Single-frame PNG, JPEG, or WebP; EXIF orientation is normalized.
* Maximum 16,384 pixels per side and 33,554,432 pixels total.
* The normal file-byte limit applies, currently 250 MiB including the normalized PNG.
* Existing Layerize credit prechecks and usage billing apply; no fixed per-image
  price or new packaging fee is introduced.
* Identical keyed retries return the same task. A changed payload or an in-flight
  duplicate returns 409 under the existing idempotency policy.
* Files use normal retention. Read-only signed URLs should be treated as secrets;
  deleting a file makes its URL unavailable. Polling does not regenerate deleted files.
* JSON and individual PNGs only: no ZIP or font binaries.