layer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Layer 通过统一且与具体模型无关的请求格式生成图像、视频、3D 网格和音频。所有任务均按 Creative Units（CUs）计价，并计入 workspace 账单。本技能集中的其他每个 skill 都以下述工作流为基础，并在此之上讲解具体方法：prompt 中应该填写什么、任务实际需要哪个 capability filter，以及如何让输出真正可用，而不只是成功生成。

客户端连接、身份验证以及与上述全部能力等效的 REST 用法，均由 Layer 已发布的

layer-connect-mcp

和

layer-generate-assets

skill 覆盖。服务器地址为

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

，使用 streamable HTTP 和 OAuth。每个 session 在首次生成前调用一次

get_instructions

，首次运行 Forge 前调用

get_forge_instructions

。

生成方式有两种。Forge 直接运行单个模型，并提供完整的参数控制，是默认方式。Workflows 运行工作室已经搭建好的多步骤 Blueprint 流水线；当用户明确指定某个 Workflow，或该任务已有可复用的流水线时，应使用它。参见

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.

步骤	工具	关键事项
确定范围	`list_workspaces`	大多数工具都需要 `workspace_id` 。如果用户有多个 workspace，应询问使用哪一个，或选择最近活跃的 workspace。
选择	`list_base_models`	传入 `filter.use_case` 并取第一个结果：默认 `sort` 是 Layer 的策划排序。
检查	`get_base_model`	查看每个模型的使用约定。有些模型要求在 prompt 中包含触发词。
上传	`request_file_upload_url` / `upload_file`	必须在生成前上传，绝不能在生成后上传。
估价	`estimate_forge_price`	免费。返回费用和执行后的余额。
运行	`execute_forge`	返回 `inference_id` 和 `poll_interval_seconds` 。
轮询	`get_forge_run`	按返回的间隔时间轮询，通常为 10 秒。

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.

绝不要硬编码

base_model_id

。模型目录受 workspace 限制且会频繁变化，因此在此处有效的 ID 到了其他位置可能会因

MODEL_NOT_FOUND

而失败。每次都要重新发现模型。

filter.use_case

是主要过滤器，涵盖以下任务类型：

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

。

仅在任务确实需要某项能力时，才使用

filter.capabilities

进一步缩小范围。它是一个布尔值对象，而不是名称列表：

filter.capabilities: {tileability: true}

。只设置需要的字段，其余字段应省略，因为

false

同样是一个过滤条件，而不是默认值。字段包括

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

和

multiple_aspect_ratios

。使用

filter.max_price

限制支出。如果过滤后没有任何结果，说明条件过于严格，应放宽过滤条件，而不是凭空指定一个模型。

Spending Creative Units

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.

每次执行前都要先估价。估价不会产生费用，并会返回运行费用、执行后的余额，以及此次运行将使用的模型，包括它是否为

auto_picked

。

费用超过 20 CUs 时，必须询问用户并等待明确同意。 服务器规定了该阈值，并明确说明不可协商，因此不要提高阈值，也不要允许用户在本 session 中提高阈值。以简短的表格呈现此次运行：生成内容、由哪个 workspace 付费，以及费用与余额的对比。

该限制按每次运行计算，因为每次估价只计算一次运行。当任务计划执行多次运行时，例如制作四帧循环或六个图标组成的素材集，应先进行估价，并在开始前展示整个运行序列的总费用，让用户一次性同意支出，而不是被反复询问四次；更糟的情况是每次运行都低于阈值，导致用户完全没有收到确认。

某些 workspace 带有

allow_negative_balance

。这表示运行不会因余额不足而被阻止，但并不意味着运行免费，也绝不能因此跳过费用确认。

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.

用户需要四个手绘等距视角建筑精灵图。

调用
```
list_workspaces
```
，获取 workspace id。

调用

list_base_models

，并设置

filter.use_case: "text_to_image"

。取第一个结果。

对该模型调用
```
get_base_model
```
，查看它是否需要触发词以及接受哪些宽高比。
使用该
```
base_model_id
```
、prompt 和
```
batch_size: 4
```
调用
```
estimate_forge_price
```
。返回费用为 7 CUs，余额为 900，因此未达到确认阈值，无需额外确认。
使用相同参数并额外传入
```
session_name
```
调用
```
execute_forge
```
，让四个精灵图在 Layer 应用中归为一组。
使用返回的
```
inference_id
```
，每隔
```
poll_interval_seconds
```
调用
```
get_forge_run
```
，直至状态为
```
COMPLETE
```
，然后提供资产 URL。

batch_size

的范围为 1 到 16，默认值为 4。它用于生成同一个 prompt 的多个变体。四个不同的精灵图需要四个不同的 prompt，因此应执行四次运行，而不是通过一次批量运行生成四个不同资产。

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.

对于本地字节数据，使用

request_file_upload_url

：它会返回用于两步式可续传上传的签名 URL 和一个

file_id

。仅当文件已经位于公开的 http(s) URL 时，才使用

upload_file

。将

file_id

值传入

guidance_files

时，应指定正确的类型：

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

。

已完成运行生成的输出资产已经带有

file_id

，可直接用于下一次运行。重新上传已经生成且带有

file_id

的资产始终是错误的做法。

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.

list_reference_sets

会返回 workspace 的训练风格。通过

reference_sets: [{set_id, weight}]

传入这些风格，最多可传 10 个；weight 的范围为 0 到 2，默认值为 1.0。使用参考集但不指定

base_model_id

时，服务器会选择一个能够应用这些参考集的模型，这通常正是所需行为：策划排序依据的是任务匹配度，而不是参考集匹配度。参见

layer-reference-sets

。

降级过程可能非常隐蔽。

reference_sets_degraded

和

reference_sets_warning

会出现在估价、执行及轮询结果中；即使运行降级，仍会成功执行并消耗 CUs。如果某个参考集未应用，应说明具体是哪一个以及未应用的原因。绝不能将已降级的参考集报告为已成功应用。

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.

用户需求	Skill
静态图像，或提示词效果未达到预期	`layer-image`
修改已有图像	`layer-image-editing`
视频，或必须按特定方式运动的镜头	`layer-video`
网格、骨骼绑定或动画	`layer-3d`
音乐、音效或语音	`layer-audio`
角色、环境、图标或游戏 UI	`layer-game-assets`
像素画、精灵图表或行走循环	`layer-pixel-art`
无缝重复的纹理	`layer-textures`
让整套素材保持统一风格，或使用训练风格	`layer-reference-sets`
已保存的多步骤流水线	`layer-workflows`
将多个片段剪辑成一段完整视频	`layer-video-timeline`
在正式投入前确定创意方向、情绪板或故事板	`layer-art-direction`
在交付前评估一批输出质量	`layer-quality`

如果此处提到的某个同级 skill 不在可用 skill 列表中，应请用户安装它（

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

）；在无人值守的情况下，可根据工具 schema 继续执行，并标明缺失的能力。

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.

根据记忆直接指定
```
base_model_id
```
，而不是动态发现模型。
未估价就执行，或未经用户明确同意便消耗超过 20 CUs。
使用固定休眠时间，而不是遵循
```
poll_interval_seconds
```
。
将
```
batch_size
```
当成一次运行生成 N 个不同资产的方法。
将已降级的参考集报告为已成功应用。
重新上传已经带有
```
file_id
```
的资产。
将
```
allow_negative_balance
```
误解为可以跳过费用确认的许可。

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.

UNAUTHENTICATED

表示 OAuth 流程从未完成，应引导用户前往其 MCP 客户端设置。

MODEL_NOT_FOUND

表示需要使用

list_base_models

重新发现模型，绝不能再次猜测。

INSUFFICIENT_BALANCE

表示应引导用户前往 Layer 应用购买额度。

RATE_LIMITED

表示并发运行数量过多，应等待或使用

cancel_inference

取消其中一次运行。

FEATURE_DISABLED

表示 workspace 未启用该功能，应引导用户联系应用内支持团队，而不是猜测如何启用该功能。