media

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.

post/media/layerize

Request

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

Headers

Moda-Version'2026-04-12' | '2026-05-01'
Example:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Request body

imagestring 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_namestring nullable

Name for the created canvas. Defaults to 'Layerized image'.

idempotency_keystring nullable

A retried call with the same key replays the stored response (replayed:true) instead of paying for a second provider render.

Response

Successful Response

object required

Changes