layer

Layer

概述

Layer 可以通过与模型无关的统一请求格式生成图像、视频、3D 网格和音频。任务按创意单位（CUs）计价，并记入工作区账单。本系列中的其他每项技能都以以下流程为基础，并在此之上讲解创作技巧：提示词中应包含什么、任务实际需要哪种能力筛选条件，以及如何让输出真正可用，而不只是生成出来。

如何连接客户端、进行身份验证，以及上述所有操作对应的 REST 用法，都由 Layer 发布的 layer-connect-mcp 和 layer-generate-assets 技能介绍。服务地址为 https://mcp.app.layer.ai/mcp，使用带 OAuth 的可流式 HTTP。每个会话中，首次生成前调用一次 get_instructions，首次运行 forge 前调用 get_forge_instructions。

有两种生成方式。Forge 直接运行一个模型，并提供完整的参数控制，是默认方式。Workflows 则运行工作室预先构建的多步 Blueprint 流程；当用户指定了某个流程，或者任务已有可重复使用的流程时，选择它。请参阅 layer-workflows。

快速参考

步骤	工具	注意事项
确定范围	list_workspaces	大多数工具都需要 workspace_id。如果用户有多个工作区，请询问使用哪个，或选择最近活跃的工作区。
选择模型	list_base_models	传入 filter.use_case，选择第一个结果：默认 sort 顺序由 Layer 精选。
检查	get_base_model	每个模型都有各自的约定。有些模型要求在提示词中加入触发词。
上传	request_file_upload_url / upload_file	必须在生成前上传，不能在生成后上传。
估价	estimate_forge_price	免费。会同时返回价格和生成后的余额。
运行	execute_forge	返回 inference_id 和 poll_interval_seconds。
轮询	get_forge_run	按返回的间隔轮询，通常为 10s。

选择模型

切勿硬编码 base_model_id。模型目录受工作区限制且会不断变化，因此在此处可用的 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 限制花费。如果筛选结果为空，说明条件过于严格；应放宽条件，而不是凭空指定模型。

消耗创作额度

每次执行前都要先估算。估算不收费，并会报告价格、执行后的余额，以及本次运行将使用的模型，包括是否为 auto_picked。

超过 20 CUs 时，先询问用户并等待明确同意。 服务端会说明此阈值，并明确表示不可协商，因此不要提高阈值，也不要允许用户在本次会话中提高阈值。用简短的表格展示本次运行的生成内容、付款工作区，以及价格与余额的对比。

此门槛按每次运行计算，因为每次估算只针对一次运行。当任务是计划好的多次运行序列（例如四帧循环或六个图标的一组）时，先估算第一轮，并在开始前展示整个序列的总价，让用户一次性同意这笔支出，而不是被询问四次；更糟的是，每次运行都低于阈值，结果一次也没询问。

有些工作区设有 allow_negative_balance。这意味着运行不会被阻止，不代表运行免费，也绝不能把它当作跳过确认的额度空间。

示例

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

1. 调用 list_workspaces，获取工作区 ID。
2. 调用 list_base_models，设置 filter.use_case: "text_to_image"。取第一个结果。
3. 对其调用 get_base_model，查看是否需要触发词，以及支持哪些宽高比。
4. 调用 estimate_forge_price，传入 base_model_id、提示词和 batch_size: 4。返回 7 CUs，余额为 900，低于门槛，因此无需确认。
5. 调用 execute_forge，传入相同参数，并添加 session_name，这样四个精灵图会在 Layer 应用中归为一组。
6. 使用返回的 inference_id 调用 get_forge_run，每隔 poll_interval_seconds 轮询一次，直到状态为 COMPLETE，然后提供资源 URL。

batch_size 的范围为 1 到 16，默认为 4。它会根据一个提示词生成多个变体。四个不同的精灵图需要四个提示词，因此是四次运行，而不是一次运行并设置批量大小为 4。

文件

对于本地字节数据，使用 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。将它直接传入下一次运行即可。重新上传生成的资源总是错误做法。

训练风格

list_reference_sets 会返回工作区中已训练的风格。通过 reference_sets: [{set_id, weight}] 传入，最多 10 个，权重范围为 0 到 2，默认为 1.0。如果传入了参考集且未指定 base_model_id，服务端会选择一个能够应用这些参考集的模型；这通常正是你想要的：精选排序依据的是任务适配度，而非参考集适配度。参见 layer-reference-sets。

降级过程不会明显提示。估算、执行和轮询都会返回 reference_sets_degraded 和 reference_sets_warning；降级运行仍会成功，也仍会消耗 CUs。如果某个参考集未能应用，请说明具体是哪一个以及原因。绝不要将已降级的参考集报告为已应用。

路由

用户想要	技能
静态图像，或效果不理想的提示词	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

如果当前可用技能中缺少此处提到的同系列技能，请让用户安装 （npx skills add layerai/skills --skill <name>）；如果无人值守，请根据工具架构继续操作，并指出这一缺失。

常见错误

• 凭记忆填写 base_model_id，而不是先查找。
• 未进行估算就执行，或未经明确同意就花费超过 20 CUs。
• 使用固定时长的休眠，而不是 poll_interval_seconds。
• 把 batch_size 当作一次运行生成 N 个不同资产的方法。
• 将降级的参考集报告为已应用。
• 对已有 file_id 的资产重新上传。
• 把 allow_negative_balance 理解为可以跳过支出确认。

错误

UNAUTHENTICATED 表示尚未完成 OAuth 流程，因此请引导用户前往 MCP 客户端设置。MODEL_NOT_FOUND 表示应使用 list_base_models 重新查找，切勿再次猜测。INSUFFICIENT_BALANCE 表示应引导用户前往 Layer 应用购买点数。RATE_LIMITED 表示并发运行过多，因此请等待，或使用 cancel_inference 取消其中一个。FEATURE_DISABLED 表示工作区缺少此功能，请指引用户联系应用内支持，不要猜测如何启用该功能。