dreamlayer

@dreamlayer/mcp

适用于兼容 MCP 的 AI 客户端的图像生成与编辑工具，由 DreamLayer Agent API 提供支持。

此工作树包含尚未发布的 0.5.0-beta.0 视频候选版本。 下方安装部分列出的已发布版本仍仅支持图像／精灵图。 如需在本地评审，请使用 Node >=22.12、pnpm install --frozen-lockfile、pnpm build， 并将 MCP 客户端配置为使用授权的视频 API 端点运行 node /absolute/path/to/dist/index.js。 这不会发布或部署任何内容。

视频候选工具

dreamlayer_video_quote 不会执行任何付费生成。dreamlayer_video_execute 仅在用户明确授权的积分上限内，执行已准备就绪且归属当前用户的报价。 切勿臆造此类授权。执行前请保存幂等键。

{"tool":"dreamlayer_video_quote","arguments":{"operation":"text_to_video","prompt":"A silent forest video","options":{"resolution":"720p","generate_audio":false,"aspect_ratio":"16:9"}}}

如需使用图像，请先通过 dreamlayer_upload_image 上传绝对本地路径， 然后使用返回的、归属当前用户的资源 ID：

{"tool":"dreamlayer_video_quote","arguments":{"operation":"image_to_video","prompt":"Restrained product showcase on a clean white background","input_asset_id":"OWNED_ASSET_UUID","context":{"use_case":"product_showcase","requested_background":"clean_white"},"options":{"model":"auto","duration_seconds":15,"generate_audio":false}}}
{"tool":"dreamlayer_video_execute","arguments":{"quote_id":"READY_QUOTE_UUID","max_credits":40,"idempotency_key":"SAVED_UNIQUE_KEY"}}
{"tool":"dreamlayer_execution","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_events","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_download","arguments":{"execution_id":"EXECUTION_UUID","path":"/absolute/new/result.mp4"}}

执行结果包含 video_job，而不是内嵌／base64 视频。状态和事件查询均为只读，不会启动任务。进度反映实际执行阶段，不会编造百分比。等待超时或响应丢失不会取消任务；使用相同报价／密钥即可找回任务。已消费的报价过期后仍可恢复。重试下载不会再次生成。

默认设置：提示词和选项均未指定时为 10s、原生 720p、除非另有要求则无音频；文本生成的宽高比为 16:9。显式指定的时长和已签发的报价保持不变。单张图像使用原生／由来源决定的宽高比。计费前会拒绝不兼容的显式设置和额外图像。

策略 video-v3-scoped-intent-10s-20261010 仅适用于新报价。 优先使用显式指定且兼容的模型；自动选择 4s 或 21–30s 时使用 Seedance。 复杂动作、较高的音频要求、连续性、白色／未知产品背景以及不确定的分类优先使用 Seedance。明显简单的非白色产品、单人对镜讲话、复古或受控电影灯光场景优先使用 FLUX。复杂度优先于风格；这些只是偏好，并非质量保证。 FLUX 支持 5–20s；Seedance 支持 4–30s。不会分析来源像素。包含口语对白时，若未指定音频则会启用音频；字幕／标签不会启用音频。前置的“no music”子句不会丢弃语音指令。非白色并不意味着同时也是白色；仅有说话者并不能说明动作简单。镜头时间戳不是时长／宽高比设置。过长的时间线会在消耗费用前失败，而不是被压缩；对白不会被截断。实时测试默认值仍为 5s。 现有报价保留其模型、提示词、设置和价格。

不包含自动跨提供商重试、保真度评分、UI 更改、扩展、升频、关键帧或多参考图像支持。下载使用归属当前用户的 30 天存储、有限流式传输、SHA-256 验证，且不会覆盖文件。 必须如实报告 pricing_pending／禁用的访问权限，不得绕过。

可用于栅格 Logo 概念、产品图像、营销视觉素材、印刷品设计概念和游戏资源。请检查输出质量及任务特定要求。 如需任务指导以及 Godot／Unity 导入示例，请参阅可安装的 Agent 工作流。

以下完整工作流使用已发布的、支持精灵图的 beta 版本。稳定版 latest 仍为 0.3.0；请使用此处显示的明确版本。

安装

将其添加到客户端。Claude Code：

claude mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/[email protected]

Codex：

codex mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/[email protected]

Cursor 或任何其他 stdio MCP 客户端：

{
  "mcpServers": {
    "dreamlayer": {
      "command": "npx",
      "args": ["-y", "@dreamlayer/[email protected]"],
      "env": { "DREAMLAYER_API_KEY": "dlr_live_your_key" }
    }
  }
}

密钥必须位于服务自身的环境中。MCP 客户端会将其作为子进程启动，因此在 shell 中导出的密钥不会传递给它。这是最常见的配置失败原因，服务会退出并说明原因，而不是在故障状态下启动。

在 platform.dreamlayer.io 获取密钥。新账户的积分为零。普通图像操作每次消耗 1 个积分；精灵图集根据下文所述的帧数报价。

工具

工具	功能
dreamlayer_capabilities	读取此密钥可执行的约定和操作。不消耗积分。
dreamlayer_balance	读取此 API 密钥的促销积分、购买积分和可用总积分。不消耗积分。
dreamlayer_upload_image	上传 PNG、JPEG、WebP 或相机 RAW 文件（最大 200 MB），并获取 input_asset_id。
dreamlayer_generate	生成或编辑图像。返回事件流。
dreamlayer_execution	读取某次执行的规范状态。
dreamlayer_events	从上次事件 ID 处继续已中断的流。
dreamlayer_download	将已完成的执行保存到新的本地路径，不会再次生成。

操作

省略 operation，DreamLayer 会读取提示词，并可能提出澄清问题。指定操作名称即可完全跳过此推断。

operation	需要图像	结果
text_to_image	否	根据提示词生成新图像
image_to_image	是	按照描述编辑参考图像
background_remove	是	将主体置于透明背景上
upscale	是	宽度和高度各扩大一倍

upscale 会将每条边扩大一倍，且完成的图像每边最长不超过 4096，因此输入图像最长边必须不超过 2048。超过此限制的图像会在消耗积分前被拒绝。

值得了解的行为

提出问题不代表失败。 模糊的提示词会返回一个以 needs_input 结束的 question 事件。调用 dreamlayer_generate，并传入 respond 和 conversation_id 来回答。

复用密钥即可安全重试。 系统会为你生成 idempotency_key。响应状态不确定时，传回相同的密钥即可重试，系统会重放原始结果，而不会重复收费。

长时间运行的任务会被截断，但不会丢失。 超过 256 个事件的流会返回已有内容，标记 truncated，并提供 execution_id 和最后一个事件 ID，供你继续读取。

错误稳定且与提供商无关。 工具错误结果包含 code、reason、message、retryable 和 request_id，与 REST 和 CLI 保持一致。模型应根据 reason 和 retryable 进行分支判断，绝不要依据消息文本。响应不会包含提示词、本地文件名、资源 URL、提供商详情、凭据或上游原始响应。

要求

Node.js 22.12 或更高版本。

许可证

MIT。请参阅 LICENSE 和 NOTICE。

Sprite-sheet beta

Sprite 请求必须且只能使用 options.animation_prompt（1–4000 个字符）或 options.action 预设（walk、run、idle）之一。自定义提示词可以描述角色、生物、物体、特效或 360° 转台动画。animation_mode 可以是 loop 或 once；预设默认为 loop，自定义提示词默认为 once。对于转台动画，请要求摄像机保持静止、主体旋转。宽泛的请求无法保证动作正确、细节完整呈现或特效成功实现透明背景。

请求整数 frame_count 7–100（默认值为 12），以及 frame_size 32、64、128、256、512、720 或 1080（默认值为 512）。这些是正方形导出画布；更大的导出尺寸不保证有更多细节。系统会保留宽高比和帧间对齐方式，并使用透明边距。生成的资源包包含透明 PNG 帧、sprite sheet、图集、预览和导入说明，其中包括每帧的播放时长。如果不需要透明背景，请在 options 中发送 background: "keep"：导出的帧会保留生成背景，呈现为普通图像而非抠图，费用按统一的普通图像价格计算。无法抠图的帧会在同一片段的相近时刻重试；若单帧仍难以抠图，该帧会保留背景，不会导致整个 sprite sheet 失败；atlas.json 会在 kept_background_frames 中列出此类帧。请选择循环播放的动画，或有起始和结束的单次动作。如果无法交付请求数量的不同帧，任务将失败，已冻结的额度会退还。半透明特效可能会丢失细节或处理失败；较小的导出尺寸不会自动变成像素画。

不同尺寸的价格相同：第 1–14 帧每帧 $0.14；后续帧每帧 $0.07。使用 background: "keep" 时，每帧统一收费 $0.07，不分阶梯，费用约为透明 sprite sheet 的一半（12 帧：5.0 点数，而非 9.9 点数）。1 点数为 $0.17。整笔订单的总价只向上取整一次，精确到十分之一点数。请在功能列表中查看 sprite_pricing，并使用 max_credits 批准报价。处理期间会冻结点数，完整交付后结算；失败或超时则会返还。客户无法取消订单。请保留执行 ID，以便恢复查看状态。自定义请求需要使用包含 broad-animation 的服务端版本；旧版服务端会拒绝此类请求。新版本的实时生成质量、100 帧时长和实际费用尚未验证。

调用 dreamlayer_upload_image，然后调用 dreamlayer_generate，并传入 operation: "sprite_sheet"、已上传的 input_asset_id、options: {action: "walk", frame_count: 12}，以及你批准的限额 max_credits。

每次工具调用都会等待一段有限时间。如果结果仍处于活动状态，请将其 execution_id 和 last_event_id 传给 dreamlayer_events。任务完成后，使用 dreamlayer_download，传入 execution_id 和以 .zip 结尾的绝对路径 path。已有文件不会被覆盖。

要确认费用是否可负担，请将完整报价（向上取整后，以点数计）与 available 比较。十分之一点数为 $0.017。促销和购买所得的点数会分别向下取整显示，因此两者显示值之和可能比 available 少 0.1 点数；实际存储的零数点数会保留。请与合计余额比较，而不是与显示值之和比较。订单费用只取整一次，不会按帧或按阶梯分别取整。

工具发现与恢复

读取 tools/list，查看描述、输入架构和操作可用性。只读调用会标记为 readOnlyHint；上传、生成和本地下载则不会。这些注释描述的是操作效果，而非权限授予。生成会启动付费任务。

每个工具都会返回 structuredContent，以及一个包含相同 JSON 的文本块，供旧版客户端使用。失败时会设置 isError: true。生成结果和错误会包含幂等键，包括由服务为你生成的键。如果需要在 MCP 进程本身丢失后仍能恢复，请在调用前选择并保存自己的键。

发生中断后，使用已保存的执行 ID 调用 dreamlayer_execution，然后使用最后处理的事件 ID 调用 dreamlayer_events。使用 dreamlayer_download 获取已完成的任务。切勿仅仅因为流已关闭就启动替代生成。重放某个键时，请保持上传的资源 ID 和参数完全相同。

MCP 设置 · API 概览 · 执行恢复

流意外失败时会触发一次规范状态读取。如果状态仍不确定，错误将为 temporarily_unavailable，并提供恢复指引以及已知的执行 ID、游标和重试键。local_output_failed 表示已完成的输出无法写入：请修复路径并重试 dreamlayer_download，而不是 dreamlayer_generate。客户端输入验证会使用 invalid_request；其他未分类的客户端失败会使用 client_error，不能据此认定生成失败。

beta.5 中的精灵图背景

options.background 用于选择帧的外观。默认值 remove 会将每一帧抠出，使其背景透明。keep 会保留生成的背景：帧保持普通状态而非抠图状态，并且每帧按固定价格 sprite_pricing.plain_frame_cents 计费，不分档，价格约为透明帧的一半。报价显示，保留背景的 12 帧需 5 个积分，透明背景则需 9.9 个积分。

beta.4 及更早版本会拒绝此字段：它们的 options 架构将 additionalProperties 设为 false，因此指定背景的请求无法到达服务。请固定使用 beta.5 或更高版本以使用此功能。

明确写出的 background: "remove" 会在发送请求前被规范化并移除，因为它与省略该字段的含义完全相同，而服务会对收到的选项生成指纹；否则，发送该字段会将同一任务拆成两个不同的幂等标识。

beta.4 中的参数描述

现在，tools/list 中的每个输入参数都会说明其接受的内容，包括嵌套的精灵图 options 字段：prompt、conversation_id、max_credits（图像操作要求恰好为 1；精灵图任务则要求不低于报价）、aspect_ratio、execution_id 和 last_event_id。工具名称、参数和结果与 beta.3 相比均未改变。

beta.3 中的错误处理更新

格式错误的事件负载会返回 response_contract_error，并将 retryable: false，同时在已知时保留执行 ID、最后事件 ID 和幂等键。请检查客户端兼容性或联系支持人员；不要提交替代任务。网络流中断后仍会核对规范状态。