Generate Cut-Out Layer Element
lab_layersProduce ONE element on a transparent background: generated, then cut out and stored as an alpha PNG in the project's gallery. This is the counter-move to the one-shot lottery — cast, props and foreground pieces are made SEPARATELY, arranged as a set afterwards and only then unified, so a wrong hand or a wrong lamp is re-made alone instead of re-rolling the whole frame. The element is deliberately optics-neutral: no lens or camera suffix travels with it, because the look is decided later on the finished comp and every layer is meant to inherit the same focal length and bokeh. ASYNCHRONOUS: the row comes back with status pending and image_url null; poll lab_job_status (type 'image') with its id until the url is populated — that url IS the cut-out. Costs credits when called without get_cost.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | What the element shows — the OBJECT or the PERSON, not the scene around them. The backend appends an isolation clause (single subject, plain seamless background, even light) so the cut-out has a clean edge; describing a set as well fights that clause and produces an element that cannot be freed. | |
| get_cost | No | Preflight: return the price in credits and your balance WITHOUT generating and without spending anything. There is no model to pick on this path — the cut-out runs on the house image model and is billed at the plain image rate, so lab_list_models has no entry that would change this number; it comes from the same cost endpoint as everywhere else. | |
| metadata | No | Free-form JSON stored alongside the element (e.g. { note, parent_id }). Merged into the row's metadata next to the fields the pipeline sets itself (kind, layer_type, status) — not interpreted. | |
| scene_ref | No | Scene label (e.g. 'SZ 04'). Stored on the row, so the element can be matched back to a shot list and reviewed per scene with lab_review_queue. Omit it and the element is an orphan in the gallery. | |
| layer_type | No | Which kind of element this is — it picks the isolation clause: 'cast' full-body person, 'prop' single object, 'foreground' a foreground piece, 'background' a wide backdrop plate WITHOUT people, 'crowd' one background performer head to feet. 'stage' is accepted by the backend but has no clause of its own and falls back to the generic one. Omit for the backend default ('prop'). | |
| project_id | Yes | Project id (from lab_list_projects) — positive integer as string. Travels in the URL; the element is filed in this project's gallery. |