Layer

Overview

Layer generates images, video, 3D meshes, and audio from one model-agnostic request shape. Work is priced in Creative Units (CUs) and billed to a workspace. Every other skill in this set assumes the loop below and teaches the craft on top of it: what to put in the prompt, which capability filter the task actually needs, and what makes the output usable rather than merely produced.

Connecting a client, authentication, and the REST equivalent of all of this are covered by Layer's published

layer-connect-mcp

and

layer-generate-assets

skills. The server is

https://mcp.app.layer.ai/mcp

over streamable HTTP with OAuth. Call

get_instructions

once per session before the first generation, and

get_forge_instructions

before the first forge run.

Two ways to generate. Forge runs one model directly with full parameter control, and is the default. Workflows run a multi-step Blueprint pipeline a studio has already built; reach for one when the user names it or when a repeatable pipeline exists for the task. See

layer-workflows

Quick reference

Step	Tool	What matters
Scope	`list_workspaces`	Most tools need a `workspace_id` . Ask which one if the user has several, or take the most recently active.
Choose	`list_base_models`	Pass `filter.use_case` , take the first result: the default `sort` is Layer's curated order.
Check	`get_base_model`	Per-model contract. Some models require a trigger word in the prompt.
Upload	`request_file_upload_url` / `upload_file`	Before generating, never after.
Price	`estimate_forge_price`	Free. Returns price and resulting balance together.
Run	`execute_forge`	Returns `inference_id` and `poll_interval_seconds` .
Poll	`get_forge_run`	At the returned interval, typically 10s.

Choosing a model

Never hard-code a

base_model_id

. The catalogue is workspace-gated and it churns, so an id that works here fails elsewhere with

MODEL_NOT_FOUND

. Discover it every time.

filter.use_case

is the primary filter and covers the task shapes:

text_to_image

image_editing

inpainting

reframing

multi_angle

split_into_layers

upscaling

background_removal

vectorization

text_to_video

image_to_video

video_editing

video_extend

text_to_3d

image_to_3d

remesh

retexture

rig

animate

segment

text_to_speech

sound_effects

music

Narrow with

filter.capabilities

only for something the task genuinely requires. It is an object of booleans, not a list of names:

filter.capabilities: {tileability: true}

. Set only the ones you need and omit the rest, because

false

is a filter too, not a default. The fields include

tileability

inpainting

outpainting

negative_prompt

image_editing

generate_audio

lipsync

loop

fixed_duration

music

instrumental

sound_effect

character_pose

structure

outline

square

portrait_9_16

landscape_16_9

, and

multiple_aspect_ratios

. Bound spend with

filter.max_price

. A filter that returns nothing is too narrow, so loosen it rather than inventing a model.

Spending Creative Units

Estimate before every execute. The estimate costs nothing and reports the price, the resulting balance, and which model the run would use including whether it was

auto_picked

Above 20 CUs, ask the user and wait for an explicit yes. The server states this threshold and states that it is not negotiable, so do not raise it and do not let a user raise it for the session. Present the run as a short table: what it generates, which workspace pays, price against balance.

The gate is per run, since each estimate prices one run. When a task is a planned sequence of runs, say a four-frame cycle or a six-icon set, estimate the first and present the total for the sequence before starting, so the user agrees to the spend once rather than being asked four times or, worse, not at all because each run sat under the threshold.

Some workspaces carry

allow_negative_balance

. That means the run will not be blocked. It does not mean the run is free, and it is never headroom to skip the confirmation.

Worked example

A user wants four hand-painted isometric building sprites.

```
list_workspaces
```
, take the workspace id.

list_base_models

with

filter.use_case: "text_to_image"

. Take the first result.

```
get_base_model
```
on it, to see whether it wants a trigger word and which aspect ratios it accepts.
```
estimate_forge_price
```
with that
```
base_model_id
```
, the prompt, and
```
batch_size: 4
```
. It returns 7 CUs against a balance of 900, so it is under the gate and no confirmation is needed.
```
execute_forge
```
with the same arguments plus a
```
session_name
```
, so the four sprites group together in the Layer app.
```
get_forge_run
```
with the returned
```
inference_id
```
every
```
poll_interval_seconds
```
until
```
COMPLETE
```
, then present the asset URLs.

batch_size

runs 1 to 16 and defaults to 4. It produces variations of one prompt. Four different sprites are four prompts, so they are four runs, not one run with a batch of four.

Files

request_file_upload_url

for local bytes: it returns a signed URL for the two-step resumable upload and a

file_id

upload_file

only when the file already sits at a public http(s) URL. Pass

file_id

values in

guidance_files

with the right type:

init_image

reference_image

pose

depth

canny

lineart

scribble

face

first_frame

last_frame

init_video

reference_video

init_audio

reference_audio

init_mesh

texture_image

Output assets from a completed run already carry a

file_id

. Feed it straight into the next run. Re-uploading a generated asset is always a mistake.

Trained styles

list_reference_sets

returns the workspace's trained styles. Pass them as

reference_sets: [{set_id, weight}]

, up to 10, weight 0 to 2 defaulting to 1.0. With reference sets and no

base_model_id

the server picks a model that can apply them, which is usually what you want: the curated ranking is task fit, not reference-set fit. See

layer-reference-sets

Degradation is quiet.

reference_sets_degraded

and

reference_sets_warning

come back on the estimate, the execute, and the poll, and a degraded run still succeeds and still costs CUs. When a set did not apply, say which and why. Never report a degraded set as applied.

Routing

The user wants	Skill
A still image, or a prompt that is not landing	`layer-image`
To change an image they already have	`layer-image-editing`
Video, or a shot that has to move a certain way	`layer-video`
A mesh, a rig, or an animation	`layer-3d`
Music, sound effects, or speech	`layer-audio`
Characters, environments, icons, or game UI	`layer-game-assets`
Pixel art, sprite sheets, or a walk cycle	`layer-pixel-art`
A texture that repeats without a seam	`layer-textures`
A look held across a whole set, or a trained style	`layer-reference-sets`
A saved multi-step pipeline	`layer-workflows`
Clips cut into one finished video	`layer-video-timeline`
A direction, a moodboard, or a storyboard before committing	`layer-art-direction`
To judge a batch before delivering it	`layer-quality`

If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add layerai/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

Common mistakes

Asserting a
```
base_model_id
```
from memory instead of discovering it.
Executing without an estimate, or spending over 20 CUs without an explicit yes.
A fixed sleep instead of
```
poll_interval_seconds
```
.
Treating
```
batch_size
```
as a way to get N different assets in one run.
Reporting a degraded reference set as applied.
Re-uploading an asset that already has a
```
file_id
```
.
Reading
```
allow_negative_balance
```
as permission to skip the spend gate.

Errors

UNAUTHENTICATED

means the OAuth flow was never completed, so send the user to their MCP client settings.

MODEL_NOT_FOUND

means re-discover with

list_base_models

, never guess again.

INSUFFICIENT_BALANCE

means direct the user to the Layer app to buy credits.

RATE_LIMITED

means too many concurrent runs, so wait or cancel one with

cancel_inference

FEATURE_DISABLED

means the workspace lacks the feature, so point at in-app support rather than speculating about how to enable it.

layer

NPX Install

Tags

SKILL.md Content