POST /v1/media/layerize-assets to receive downloadable PNG
layers and JSON text details. Use normal API-key authentication
with media:generate and tasks:read. No feature flag, canvas-write scope, or export scope is required.
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 withkind: "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 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
Onstatus: "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.