aetherwave-mcp

@aetherwave-studio/mcp

适用于 AetherWave Studio 的模型上下文协议服务。将其接入任何兼容 MCP 的客户端（Claude Code、Cursor、Continue、Claude Desktop、自定义 Agent），你的大模型即可通过一个 API 密钥和一个积分池，使用所有旗舰级创意 AI 提供商生成、编辑、放大、重新构图和母带处理内容。

一次安装。一个令牌。默认提供 33 个工具，涵盖：

• 音乐 - Suno V3.5 / V4 / V4.5 / V5 / V5.5
• 图像生成 - Grok Imagine、GPT Image 2、Seedream V4、Wan 2.7、Nano Banana 2、Flux 2、Qwen Image、Z-Image Turbo
• 图像编辑 - Grok Imagine I2I、Seedream V4 Edit、Flux Kontext、Wan 2.5 Spicy、Qwen Edit、GPT Image 1.5
• 图像实用工具 - 2x / 4x 放大、Recraft 背景移除（备选方案为 fal BiRefNet v2）、Ideogram V3 重新构图
• 视频 - Grok Imagine（KIE+fal 备选方案）、Wan 2.7、Hailuo 02、Seedance Pro/Lite、Kling 2.6（音频）、VEO 3.1、Happy Horse
• 视频实用工具 - Atlas 放大器（1080p/2K）、rembg u2netp 背景移除、Luma Ray 2 Flash 重新构图
• 音频母带处理 - 通过 AetherWave Python 服务提供 12 种流派/风格预设
• 图库 - 上传自己的图像、音频和视频（本地文件、URL 或数据 URL），并分页列出已保存的作品
• 用户手册 - MCP、Graphic Novel Studio、UGC Studio 和 Project Studio 的 PDF 链接（保存在 npx 服务的 Downloads 目录中）
• 漫画书 - 9 个工具端到端驱动 AetherWave Graphic Novel Engine：演员阵容、角色参考图、剧本、分镜、带文字的页面，以及 PDF / EPUB / CBZ 下载链接
• 周边商品 - 4 个工具：服装目录、设计生成样品图，以及另外 2 个工具（需提供 PRINTFUL_API_TOKEN）用于在你自己的 Printful 商店中创建和列出商品，另有 1 个管理用店铺列表工具

每个生成工具都会提交任务，并在最多 45 秒的软时限内等待结果。快速任务会在一次往返中返回最终 URL；耗时较长的任务会返回 state: "running" 和 taskId，而 aetherwave_get_job 支持轮询所有工作流（图像、视频、音乐、母带处理、漫画、周边商品）。在任何工具中传入 async: true 即可立即返回。结果会自动保存到你的 Cloudflare R2 图库，因此 URL 不会过期。

漫画工具从一开始就围绕这一点设计：绘制一本书大约需要一小时，因此每个耗时步骤都会立即启动并返回，Agent 可通过 aetherwave_comic_status 查看进度。请参阅使用 MCP 制作漫画书。

快速开始

# 1. Get a key at https://aetherwavestudio.com/profile (Developer tab)
# 2. Add to your MCP client config (see below)
# 3. Restart the client
# 4. Ask your agent to "generate a synthwave album cover, then animate it"

Claude Code

claude mcp add aetherwave \
  -e AETHERWAVE_API_KEY=aw_live_your_key_here \
  -- npx -y @aetherwave-studio/mcp

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "aetherwave": {
      "command": "npx",
      "args": ["-y", "@aetherwave-studio/mcp"],
      "env": {
        "AETHERWAVE_API_KEY": "aw_live_..."
      }
    }
  }
}

重启 Claude Desktop。

Cursor

在 Cursor Settings -> MCP -> Add new server 中：

{
  "aetherwave": {
    "command": "npx",
    "args": ["-y", "@aetherwave-studio/mcp"],
    "env": { "AETHERWAVE_API_KEY": "aw_live_..." }
  }
}

Continue（VS Code / JetBrains）

在你的 ~/.continue/config.yaml 中：

mcpServers:
 - name: aetherwave
    command: npx
    args: ["-y", "@aetherwave-studio/mcp"]
    env:
      AETHERWAVE_API_KEY: aw_live_...

自定义 / 编程客户端

标准 stdio MCP 服务。任何按照 MCP 规范通过 stdio 使用 JSON-RPC 2.0 通信的客户端均可连接：

AETHERWAVE_API_KEY=aw_live_... npx -y @aetherwave-studio/mcp

工具一览

工具	用途
aetherwave_list_characters	已保存的 UGC 角色，包含身份信息块、参考包、声音和个性
aetherwave_get_job	轮询工具返回的任何 state: "running" 作业（或使用 async: true 提交的作业），或恢复调用超时的作业。涵盖图像、视频、视频编辑、音乐、周边商品模型图和漫画导出
aetherwave_balance	当前积分余额和套餐
aetherwave_list_image_models	列出所有图像模型及其费用、速度和 I2I 支持情况
aetherwave_list_video_models	列出所有视频模型及其每秒费用、时长和分辨率
aetherwave_list_master_presets	列出 12 种母带处理预设及其目标 LUFS、标签和描述
aetherwave_generate_image	使用 8 种以上模型进行 T2I 或 I2I。默认使用 grok-imagine-t2i（6 积分，输出 2 张图像）
aetherwave_generate_video	使用 7 种以上模型系列进行 T2V 或 I2V。支持原生音频、参考图像身份锁定和异步提交
aetherwave_generate_music	默认使用 Suno V5.5。每次提交生成两首曲目，支持歌词和纯音乐
aetherwave_edit_image	I2I 编辑。默认使用 grok-imagine-i2i（10 积分，输出 1 张图像）
aetherwave_upscale_image	放大 2 倍或 4 倍，4 积分
aetherwave_reframe_image	使用 Ideogram V3 Reframe 调整到新的宽高比（向外扩展边缘）
aetherwave_remove_background	优先使用 Recraft，失败时回退到 fal BiRefNet v2（自动故障转移）。输出自动保存到图库
aetherwave_upscale_video	使用 Atlas（1080p、2K）或 BytePlus（1080p 至 8K）放大视频
aetherwave_remove_background_video	通过 rembg u2netp 逐帧移除背景。输出透明 WebM 或纯色背景视频。每秒 2 积分
aetherwave_reframe_video	使用 Luma Ray 2 Flash 调整到新的宽高比
aetherwave_master_audio	使用 12 种流派／风格预设进行 AI 母带处理。每首曲目 20 积分；Producer / Mogul / Ultimate 套餐免费
aetherwave_list_my_creations	分页读取图库，供串联工作流使用
aetherwave_upload_to_gallery	从本地文件（仅限 npx）、URL 或数据 URL 将自己的图像、音频或视频添加到图库。免费，占用存储空间，最大 95 MB
aetherwave_get_user_manual	用户手册 PDF 链接（mcp、graphic-novel、ugc-studio、project-studio）；在 npx 服务上还会将手册保存到 Downloads
aetherwave_comic_estimate	免费获取漫画报价：根据页数估算剧本和分镜积分
aetherwave_comic_create	创建漫画项目（标题、故事梗概、角色阵容、艺术风格）。免费
aetherwave_comic_character_reference	生成（每张 6 积分）或批准角色参考图像
aetherwave_comic_write_script	开始撰写剧本（2-3 分钟；使用时收费；12 页约 40 积分）
aetherwave_comic_draw	开始绘制所有尚未绘制的分镜（每格 9 积分，成功后收费）。可安全地再次调用
aetherwave_comic_status	查看进度、停滞的运行、失败分镜及原因、页面 URL 和下一步。免费
aetherwave_comic_redraw_panel	重绘一格，可选择修改场景描述（成功后收费 9 积分）
aetherwave_comic_assemble	排版并为页面添加文字（每页约 4 秒）。免费
aetherwave_comic_export	导出为 PDF、EPUB、CBZ 或打包文件，提供有效期约一天的下载链接。免费

每个生成工具的描述中都包含模型选择指南。Agent 可根据提示词意图选择合适的模型，无需通过 list_image_models 或 list_video_models 反复查询。

使用 MCP 制作漫画

九个工具从头到尾驱动 AetherWave Graphic Novel Engine，让 Agent 能将一句话变成一部完成并排好字的漫画。你可以这样说：

给我制作一部 12 页的法比利亚漫画，讲述一名 14 岁的信使和她爱抱怨的机械师叔叔，夜间驾驶村里最后一艘航空邮政气球飞越阿尔卑斯山，递送一封能阻止大坝淹没他们家园的信。适合所有年龄段。花费不超过 350 点数。

然后 Agent 会按以下顺序运行：

步骤	工具	作用	时间	点数
1	aetherwave_balance	确认由哪个账户付款，以及余额是否足以支付这本漫画	即时	0
2	aetherwave_comic_estimate	报出费用上限（假设每页 4 格）	即时	0
3	aetherwave_comic_create	创建项目和角色阵容；返回 projectId 和每个角色的 characterId	几秒	0
4	aetherwave_comic_character_reference，参数为 action: "generate"	按漫画风格为每个角色绘制全身参考图	最长约一分钟	每个 6 点数
5	aetherwave_comic_character_reference，参数为 action: "approve"	锁定选定的图像；每格都会使用它来保持人物面容一致	几秒	0
6	aetherwave_comic_write_script	开始编写剧本：章节、页面、分格、对话和说明文字	2-3 分钟	使用时扣费
7	aetherwave_comic_status	轮询，直到 projectStatus 为 script-ready，然后读取实际分格价格 creditsToFinishDrawing	即时	0
8	aetherwave_comic_draw	开始逐格绘制；maxCredits 可限制此次运行的费用	每格 1.5-6 分钟	成功后每格 9 点数
9	aetherwave_comic_status	每隔几分钟轮询一次。drawing: "stalled" 表示此次运行结束时仍有未完成的分格：再次调用 aetherwave_comic_draw	即时	0
10	aetherwave_comic_redraw_panel	如果某个分格因内容审核拒绝而反复失败：改写该场景并重新绘制	1.5-6 分钟	成功后 9 点数
11	aetherwave_comic_assemble	排版并为每页添加文字	每页约 4 秒	0
12	aetherwave_comic_export	返回 PDF（或 EPUB / CBZ / bundle）下载链接	约 15-30 秒	0

实测案例

《最后的气球邮递》（2026-09-25）完全按照这种方式制作，使用的正是这些工具调用的同一 API：

• 12 页、27 格、301 点数：27 格 x 9 = 243，剧本 40，三个角色参考图 18。由于假设 12 页共 48 格，估算时报价为 462。剧本生成后，请根据 creditsToFinishDrawing 重新估算。
• 绘制约 65 分钟，每格 1.5 到 6 分钟，并且严格按顺序逐格进行。整个流程约 80 分钟。
• 过程中有 9 格绘制失败，均未扣费：3 次被内容过滤器拒绝，4 次上游“Internal Error”偶发故障，2 格因服务重启而中断。每一格都在之后的运行中成功绘制。
• 12 页的排版耗时约 45 秒。PDF 大小为 130 MB，因此导出时返回的是链接，而不是文件。

Agent 应遵循的规则

• 先批准参考图，再编写脚本。 批准操作会根据图片重新描述角色，脚本编写者会读取这段描述。没有已批准参考图的角色只能根据文字绘制，其面孔会在各个分格之间发生变化。
• 切勿将已停止的运行视为已完成。 服务重启会悄无声息地终止绘图运行。只要仍有分格待处理或失败，且没有运行处于活动状态，aetherwave_comic_status 就会报告 drawing: "stalled"。可以安全地再次调用 aetherwave_comic_draw：它只会绘制缺失的内容，绝不会重复启动（第二次启动会报告 alreadyDrawing）。
• 改写提示词，不要重试被拒绝的分格。 状态中的 failedPanels[].errorMessage 会说明原因。内容审核拒绝后，简单重试仍会被拒绝；使用新的 prompt 调用 aetherwave_comic_redraw_panel，即可替换该次绘图的场景描述。成人与儿童发生肢体接触的场景会被图像过滤器拒绝。
• 重写脚本会删除所有分格。 如果项目已有分格，aetherwave_comic_write_script 会拒绝执行，除非设置 replaceExisting: true。
• 对已组装页面上的分格重新绘制后，要再次组装； aetherwave_comic_status 会在 pages.staleSinceAssembly 下列出这些页面。
• 只有永久图片才能用作参考图。 approve 会拒绝临时链接（例如原始的服务提供方结果 URL），因为链接过期后，漫画书就会失效。
• 每个漫画工具的结果都包含 account：付费的 AetherWave 用户名。如果使用多个 MCP 连接，请检查此字段。

使用自己的角色以编程方式生成视频

以上工具组合起来，能实现 API 过去做不到的事：向 Agent 提供一段描述，就能获得一部完成的多镜头影片，由你已创建的角色主演，并且全程保持面孔和声音一致。

UGC 角色是你在 AetherWave 中保存的、会反复出镜的人物，包含固定的外观、已批准的参考图包、声音和性格。Agent 可通过 aetherwave_list_characters 发现这些角色。如果没有这个工具，被告知 “用我的 Amy 角色拍这个” 的 Agent 就无从得知 Amy 是谁，只能为每个片段编造不同的面孔。

工作循环

// 1. Discover the character. There is no other way to find them.
const { characters } = await listCharacters({ name: "amy" });
const amy = characters[0];

// 2. Build every prompt from her stored identity - VERBATIM, never paraphrased.
//    Identical text is identical conditioning; that IS the consistency mechanism.
const prompt = [
  shotDescription,
  amy.identityBlock,                    // "CORE IDENTITY: same woman, Nordic, ..."
  `Her speaking voice: ${amy.voiceSpec ?? amy.voiceDescriptor}`,
  `She says exactly this and nothing else: "${line}"`,
].join("\n\n");

// 3. Submit async, anchored to her approved pack, with audio on.
const { taskId } = await generateVideo({
  prompt,
  model: "seedance-2-mini",
  duration: 12,
  resolution: "480p",
  aspectRatio: "16:9",
  generateAudio: true,                  // without this the clip is SILENT
  referenceImages: amy.referenceImages, // NOT imageUrl - that drops the anchors
  async: true,                          // returns in ~2s, survives the client timeout
});

// 4. Poll until the render lands.
let job;
do { await sleep(15000); job = await getJob({ taskId, kind: "video" }); }
while (!job.done && !job.error);

// 5. Repeat per shot, then assemble the clips in order.

真正能保持角色一致性的四条规则

1. 将 identityBlock 原样附加到每条提示词中。 用自己的话重写会破坏锁定——机制完全依赖文本完全相同。
2. 传入 referenceImages，绝不要传入 imageUrl。 使用首帧会让引擎切换到首帧模式，并丢弃锚点。当角色已有已批准的参考图包时，该参考图包会取代主图，而非与其并用；混合使用会使面孔朝两个方向偏移。
3. 各片段中的声音文本必须逐字节保持一致，原因与身份描述块相同。
4. 任何包含对白的内容都要设置 generateAudio: true。 此项默认关闭，而且在 Seedance 2.x 上免费，因此静音片段从来不是更便宜的选择——只会更差。

按时长撰写台词

duration 是决定性参数。引擎会按要求的秒数生成，误差约为 0.1 秒，然后通过调整语速来适配台词长度，而不是提前结束。因此，应根据片段时长写台词，而不是根据台词长度定片段时长——实测可行的参考值约为每秒 2 个单词。声音描述中的每分钟单词数描述的是角色，而非引擎；按此规划曾导致一部 22 个片段的作品超时 35%。

生僻词要按实际发音拼写："super intelligence" 比 "superintelligence" 更容易正确呈现。

⚠️ 在合成前核验语音

一次生成可能说错了词语，却仍会返回 success 和一个 URL。重新渲染完全相同的提示词，可能一次生成正确，另一次却漏掉整句话——这是每次生成的随机性导致的，而响应中没有任何信息能区分两者。在一个包含 22 个片段的制作中，有 4 个片段读错了，而且不听就无法发现。

对于任何无人值守的合成流程，请先转录每个片段，并对照你要求的台词进行评分，然后再使用；未通过的片段要重新生成。检查不花钱，片段却已经消耗了额度。请对照脚本评分，而不是对照上一步传来的内容。

在对话中销售周边（Printful）

只需提出需求，就能把任意设计制作为按需印刷商品：

“制作一件印有 NIGHT SHIFT 字样的 T 恤，字体为镀铬效果，印在黑色 Bella+Canvas 3001 上，给我看看样机，然后以 $29.99 添加到我的 Printful 商店。”

工具	费用	功能
aetherwave_merch_garments	免费	T 恤、背心、连帽衫、帽子：颜色、美国有货尺码、以英寸为单位的印刷区域、刺绣线颜色
aetherwave_merch_prepare_design	1 个额度	将任意图像（AetherWave URL、数据 URL 或本地文件路径）处理为透明、裁切后的印刷 PNG。knockout 会移除纯色背景，同时保留图案内部的白色字样
aetherwave_merch_mockup	3 个额度	按服装的实际印刷区域和 DPI 制作印刷文件，然后渲染 Printful 样机。渲染失败会退还额度；服装、颜色或位置不合适不会收费。每小时 20 次
aetherwave_merch_mockup_status	免费	查询超过 90 秒等待时间的渲染任务
aetherwave_printful_create_product	免费	在你自己的 Printful 商店中创建商品
aetherwave_printful_list_products	免费	列出你商店中的商品

连接你的 Printful 商店

将 Printful 令牌添加到服务的环境变量中。该令牌仅用于你的设备与 api.printful.com 之间；不会发送给 AetherWave。

{
  "mcpServers": {
    "aetherwave": {
      "command": "npx",
      "args": ["-y", "@aetherwave-studio/mcp"],
      "env": {
        "AETHERWAVE_API_KEY": "aw_live_...",
        "PRINTFUL_API_TOKEN": "your Printful private token",
        "PRINTFUL_STORE_ID": "only needed for account-level tokens"
      }
    }
  }
}

在 Printful 的 Settings > API 下创建令牌（限制到一个商店的私有令牌最简单）。只有设置了 PRINTFUL_API_TOKEN，且运行的是本地 npx 服务时，才会显示这两个 aetherwave_printful_* 工具；远程连接器绝不会索要你的商店密钥。商品会创建在 Printful 中；照常在那里发布到 Shopify、Etsy 和其他已连接的渠道。

推广商品之前： Printful 会按订单收费（服装、运费，在美国通常还包括销售税）。请确认零售价足以覆盖这些费用。你是卖家：只能印制你有权使用的图案和文字。

Printify： 即将推出。它的商品目录运作方式不同（同一件服装可能由多个印刷服务商提供，价格和库存也各不相同），因此会为它单独开发工具，而不是用一个半成品开关。

工具参考

aetherwave_balance

返回当前额度余额。无需输入。

返回： { credits, plan, ... }

aetherwave_list_image_models

返回所有图像模型及其额度费用、支持的输入、分辨率和宽高比选项。无需输入。

返回： { models: [...] }

aetherwave_list_video_models

返回所有视频模型及其每秒额度费用、时长、分辨率和宽高比。无需输入。

返回： { models: [...] }

aetherwave_list_master_presets

返回所有母带处理预设及其目标 LUFS、标签、描述和难度。如果不知道哪种预设适合这首曲目，请在调用 master_audio 之前先调用此工具。

返回： { presets: [...] }（每项包含：{ id, name, description, target_lufs, tags, difficulty, icon }）

aetherwave_generate_image

T2I 或 I2I。提交任务、轮询并返回最终 URL。

参数	类型	必填	默认值	说明
prompt	string	是	-	图像的文字描述
model	string	否	grok-imagine-t2i	模型 ID。使用 list_image_models 查看完整列表
aspectRatio	string	否	模型默认值	例如 1:1、16:9、9:16
resolution	string	否	模型默认值	1K、2K，部分模型支持 480p/720p
referenceImages	string[]	否	-	I2I 使用的 URL；若模型为 I2I，则必填
numImages	int (1-8)	否	模型默认值	用于多输出模型
negative_prompt	string	否	-	部分模型支持
seed	int	否	-	确定性生成，部分模型支持

选择提示（内置于工具描述中）： 单张最佳图像 → gpt-image-2-t2i（1K 为 9 cr，2K 为 12 cr）。照片级真实感 → gpt-image-2-t2i 或 nano-banana-2。图像中文字 → gpt-image-2-t2i。NSFW → wan-2.5-spicy-t2i。高端 → grok-imagine-quality-t2i（14 cr）。最便宜 → z-image-turbo（2 cr）。

返回： { taskId, state, images, autoSaved, creationIds }

aetherwave_list_characters

你保存的 UGC 角色——与你合作拍摄的、会反复出现且有名字的人物——以及在整个制作过程中保持角色一致所需的一切。只要请求中提到用户已有的人物，就先调用此工具。

参数	类型	必填	说明
name	string	否	按名称或 handle 进行不区分大小写的子字符串筛选。省略则列出全部

返回： { count, characters[], usage }，每个角色包含：

字段	重要性
identityBlock	锁定的核心身份字符串。将其原样附加到每个提示词中
referenceImages	已批准的素材包。在 generate_video 中作为 referenceImages 传入
hasApprovedPack	若存在素材包则为 True；优先使用素材包，而非 heroImageUrl
heroImageUrl	对于没有素材包的角色，单张备用锚定图
voiceId / voiceSpec / voiceDescriptor	语音条件文本；在各片段间保持字节完全一致
personality	用户编写的语气、特点和说话风格等方向
negativeLock	角色的负面提示词
engineParams	各模式的参考强度

长时间运行的任务会在 45 秒内返回

MCP 客户端（claude.ai、Claude Desktop、Cursor）会在大约 60 秒后放弃工具调用。在 0.3.0 之前，每个长时间运行的工具都会阻塞 6 到 15 分钟，因此，一个耗时 90 秒的图像渲染会在客户端显示为“失败”，但任务仍会完成并扣费，而 taskId 会随被放弃的调用一起失效。

现在，所有提交任务的工具（generate_image、edit_image、upscale_image、reframe_image、remove_background、generate_video、upscale_video、reframe_video、remove_background_video、generate_music、merch_mockup、comic_export）最多轮询约 45 秒，然后返回：

{ "state": "running", "taskId": "…", "kind": "image", "checkWith": "aetherwave_get_job", "pollEverySeconds": 10, "next": "…" }

使用该 taskId 和 kind 轮询 aetherwave_get_job，直到状态为 done。这些工具均提供两种明确的例外选项：

参数	效果
async: true	提交任务后立即返回 taskId，不进行轮询
wait: true	使用旧版长时间阻塞模式（预算为 6-15 分钟）。仅当客户端允许调用超过 60 秒时使用

master_audio 没有任务 ID（请求本身就是任务）：它也会在约 45 秒内返回；若母带处理耗时超过调用时长，结果会保存到图库中——使用 aetherwave_list_my_creations 并将类型设为 audio 查找，切勿重新提交。

aetherwave_get_job

通过 taskId 检查任务。对于任何 state: "running" 的结果、async: true 提交后的任务，或任何调用超时的生成任务，都应使用此工具进行恢复，因为任务会继续在服务端运行，并保存到你的图库中，不受客户端发生的情况影响。

参数	类型	必填	说明
taskId	string	是	工具返回的 taskId（或 taskKey / exportId）
kind	enum	是	image（生成、编辑、超分辨率、重新构图、移除背景）、video、video-edit（视频超分辨率／重新构图／移除背景）、music、merch-mockup、comic-export
projectId	string	对于 comic-export 必填	导出所属的漫画项目

返回： { taskId, kind, state, done, failed, videoUrl, imageUrls, tracks, mockups, downloadUrl, autoSaved, creationIds, error, next, raw }

aetherwave_generate_video

T2V 或 I2V。提交任务、轮询最多约 45 秒，并在渲染完成时返回 URL；否则返回 state: "running" 和 taskId（视频需要 1-8 分钟，因此通常会返回这种情况）。

参数	类型	必填	默认值	说明
prompt	string	是	-	对场景的文字描述
model	string	否	grok-imagine-t2v	模型 ID。使用 list_video_models
duration	int (2-30)	否	模型默认值	秒数。Grok 支持 6-15 秒
resolution	enum	否	模型默认值	480p、720p、1080p、2K
aspectRatio	string	否	模型默认值	例如 16:9、9:16、1:1
imageUrl	string	否	-	I2V 模型必填
endImageUrl	string	否	-	部分 I2V 模型支持首帧和末帧
mode	enum	否	normal	Grok Imagine：fun、normal、spicy
generateAudio	bool	否	false	随视频渲染语音／声音。 不启用时，片段没有声音。Seedance 2.x 在所有分辨率下均免费
referenceImages	string[] (max 9)	否	-	在整个片段中保持一致的身份锚点。不能与 imageUrl 同时使用。系统会为你获取并编码 https URL
async	bool	否	false	立即返回 taskId，而不是等待
wait	bool	否	false	最多阻塞 8 分钟。仅当客户端允许调用超过 60 秒时使用

返回（已完成）： { taskId, state, videoUrl, fallbackProvider, autoSaved, creationId, kieTaskId } 返回（仍在渲染或设置了 async）： { state: "running", taskId, kind: "video", checkWith, pollEverySeconds, next }

渲染需要 1-8 分钟，而大多数 MCP 客户端会在 60 秒时放弃调用（MCP error -32001），因此此工具会在约 45 秒内返回 state: "running"，随后你可以轮询 aetherwave_get_job。无论客户端如何处理，任务都会提交、计费并保存到你的图库中。

⚠️ imageUrl 和 referenceImages 不能叠加使用。 提供首帧后，引擎会专门切换到首帧模式，并丢弃参考图像——这会在不提示的情况下禁用唯一可用的防止漂移机制。同时传入两者会被明确报错拒绝，而不是悄悄采用其中一个。

aetherwave_generate_music

Suno 音乐生成。每次提交生成两首曲目。

参数	类型	必填	默认值	说明
prompt	string	是	-	风格／情绪／主题描述
instrumental	boolean	否	false	若为 true，则不含人声
model	enum	否	V5_5	V3_5、V4、V4_5、V5、V5_5
title	string	否	-	曲目的可选标题
lyrics	string	否	-	自定义歌词；省略则由 Suno 撰写

返回： { taskId, status, tracks }

aetherwave_edit_image

由文本提示词引导的图生图编辑。

参数	类型	必填	默认值	说明
prompt	string	是	-	编辑内容的文本描述
imageUrl	string	是	-	源图像的公开 URL
model	string	否	grok-imagine-i2i	10 cr，单张图像
aspectRatio	string	否	源图像比例	例如 1:1、16:9
resolution	string	否	模型默认值	部分模型支持：1K、2K、4K
quality	enum	否	模型默认值	low、medium、high（GPT Image）
maxImages	int (1-8)	否	-	适用于多输出模型
renderingSpeed	enum	否	模型默认值	turbo、balanced、quality
negative_prompt	string	否	-	部分模型支持

选择建议： 细微编辑／角色一致性 → flux-kontext-pro。NSFW → wan-2.5-spicy-i2i。追求最高质量 → gpt-image-1.5-i2i 或 grok-imagine-quality-i2i。单张输出／4K → seedream-v4-edit。

URL 注意事项： 源 URL 中包含空格或括号时，上游处理可能失败。建议使用不含特殊字符的简洁 URL。

返回： { taskId, state, images, autoSaved, creationIds }

aetherwave_upscale_image

以固定 4 个 credits 放大 2 倍或 4 倍。

参数	类型	必填	默认值	说明
imageUrl	string	是	-	源图像的公开 URL
upscaleFactor	enum	否	2x	2x 或 4x

credits 消耗量按源分辨率 × 倍数计算。

返回： { taskId, state, images, autoSaved, creationIds }

aetherwave_reframe_image

Ideogram V3 Reframe。扩展图像边缘以适应新的宽高比。

参数	类型	必填	默认值	说明
imageUrl	string	是	-	源图像的公开 URL
aspectRatio	string	是	-	目标比例：1:1、16:9、9:16、4:3、3:4、21:9
speed	enum	否	balanced	turbo（5 cr）、balanced（10 cr）、quality（14 cr）

返回： { taskId, state, images, autoSaved, creationIds }

aetherwave_remove_background

首选 Recraft，备用 fal.ai BiRefNet v2。每张图像约 5 cr。

参数	类型	必填	默认值	说明
imageUrl	string	是	-	源图像的公开 URL

返回： { taskId, state, images }（带透明 Alpha 通道的 PNG）

aetherwave_upscale_video

提供两种引擎。Atlas 最高支持 1080p 和 2K；BytePlus 最高支持 1080p、2K、4K 和 8K，且 4K 和 8K 会自动选择 BytePlus。

档位不等于尺寸：这些名称对应 16:9 标准，因此源视频会适配到该档位的框内，并以较小的尺寸为准。4k 档位下的正方形源视频会输出 2160x2160，而非 3840x3840。若要精确指定像素尺寸，请选择合理的最高档位，然后使用 ffmpeg 调整尺寸。

参数	类型	必填	默认值	说明
videoUrl	string	是	-	源视频的公开 URL（MP4）
targetResolution	enum	否	1080p	1080p、2k、4k、8k。Atlas：1080p 为 7 cr/s（最长 53s），2k 为 10 cr/s（最长 23s），源视频帧率须为 30fps 或更低。BytePlus：4 / 8 / 16 / 62 cr/s
upscaleProvider	enum	否	1080p/2k 时为 atlas	atlas 或 byteplus。4k 和 8k 始终使用 BytePlus 处理

返回： { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_remove_background_video

通过 AetherWave 的 Python 服务使用 rembg u2netp 逐帧移除背景。2 cr/sec。

参数	类型	必填	默认值	说明
videoUrl	string	是	-	源视频的公开 URL（MP4）
bgType	enum	否	transparent	transparent = Alpha WebM，color = 纯色替换
customColor	string	否	#00ff00	当 bgType: "color" 时用于纯色替换的十六进制颜色

返回： { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_reframe_video

Luma Ray 2 Flash 重构为新的宽高比。17 cr/sec。

参数	类型	必填	默认值	说明
videoUrl	string	是	-	源视频（MP4）的公开 URL
reframeAspectRatio	enum	是	-	16:9、9:16、1:1、4:3、3:4、21:9
reframePrompt	string	否	-	用于引导新边缘内容的可选提示词（例如“将天空扩展为带有日落云彩的天空”）

返回： { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_master_audio

通过 AetherWave Python 服务进行 AI 母带处理。同步响应（路由会在内部轮询，预计耗时 30 秒至 5 分钟）。每首曲目 20 个积分。Artist、Producer、Mogul 和 Ultimate 套餐免费。输出为 WAV（每首 3 分钟的曲目约 50 MB），并自动重新托管到 Cloudflare R2。

参数	类型	必填	默认值	说明
audioUrl	string	是	-	MP3 或 WAV 的公开 URL
preset	string	是	-	12 种之一（见下文）
trackTitle	string	否	-	可选的图库条目标题

预设列表（12 种，通过 /api/master-presets 实时获取）：

预设	名称	目标 LUFS	适用场景
streaming	流媒体就绪	-14	Spotify、Apple Music、YouTube
loud	响亮有力	-9	追求竞争力响度
gentle	温和处理	-16	原声、古典、爵士
hip_hop	嘻哈 / Trap	-11	强劲低音 + 清脆高音 + 808
edm	EDM / 电子乐	-10	House、techno、dubstep、高潮段落
pop	流行 / 排行榜金曲	-12	适合电台播放的润色效果
rock	摇滚 / 另类	-12	有力的中频、粗粝质感
lofi	Lo-Fi / 轻松	-14	温暖、放松
rnb	R&B / 灵魂乐	-13
acoustic	原声 / 民谣	-16	保留动态范围
cinematic	电影 / 管弦乐	-18	宽广的动态范围
podcast	播客 / 人声	-16	突出人声

返回： { success, masteredUrl, preset, trackTitle, creditsCharged, isFree }

aetherwave_upload_to_gallery

将用户已有的文件保存到其 AetherWave 图库，并返回其他所有工具都可接受的永久 URL。免费（不消耗积分）；文件会占用账户存储空间，若上传文件超过套餐存储容量，系统会拒绝上传并告知剩余空间。

参数	类型	必填	说明
filePath	string	三选一	此计算机上的文件。仅限 npx 服务端；远程连接器无法读取你的磁盘
url	string	三选一	公开的 http 或 https 链接。由服务端获取；若链接解析到私有或内部地址，则会被拒绝
dataUrl	string	三选一	data: URL
title	string	否	图库标题。默认为文件名
description	string	否
tags	string[]	否	最多 20 个

支持的类型：图片 png jpg webp gif，音频 mp3 wav m4a flac ogg，视频 mp4 webm mov。每个文件最大 95 MB；更大的文件请通过网站上传工具上传。

返回： { success, creationId, url, type, title, sizeBytes }

aetherwave_get_user_manual

用户手册 PDF 的下载链接。在 npx 服务端上，还会将 PDF 保存到用户的 Downloads 文件夹（或 saveTo），并返回保存路径。免费。

参数	类型	必填	默认值	说明
manual	enum	否	mcp	mcp、graphic-novel、ugc-studio、project-studio
saveTo	string	否	Downloads	仅限 npx 服务端。文件夹，或 "none"（表示仅返回链接）

返回： { manual, title, url, savedTo?, sizeBytes? }

aetherwave_list_my_creations

分页画廊读取。适用于串联操作（“将我最近的 5 张图片重新构图为 9:16”）。

参数	类型	必填	默认值	说明
type	枚举	否	all	image、video、audio
limit	int (1-500)	否	100	最大项目数
offset	int	否	0	分页偏移量
favoritesOnly	boolean	否	false	仅筛选收藏项

返回： { items, total, offset, limit, hasMore }。每个项目：{ id, type, title, prompt, model, createdAt, isFavorite, contentUrl, thumbnailUrl, visibility, rating, duration?, width?, height?, likeCount, totalPlays, metadata }。

漫画书工具

这九个工具均封装了 Graphic Novel Studio Web 应用使用的 /api/graphic-novel/* 路由，因此通过 MCP 创建的漫画可以在工作室中打开，反之亦然。每个结果都包含 account，即计费的用户名。

aetherwave_comic_estimate

免费上限报价。按每页 4 格计算，因此短篇漫画通常花费更少（12 页：报价 462，成本 301）。

参数	类型	必填	默认值	说明
pageCount	int (4-64)	是	-	工作室提供 12、16、24、32、48、64 页
imageModel	枚举	否	gpt-image-2	gpt-image-2（更快：GPT Image 1.5 绘制分格 + GPT Image 2 绘制封面）或 gpt-image-2-5（质量更高，速度较慢）。无论哪种方案，每格均为 9 cr

返回： { account, scriptCredits, panelCredits, assumedPanels, creditsPerPanel, totalCredits, imageModel, note }

aetherwave_comic_create

创建项目及其角色阵容。免费。尚未生成任何内容。

参数	类型	必填	默认值	说明
title	string	是	-	绘制在封面分格中
premise	string	是	-	情境、目标和利害关系
characters	array (1-12)	是	-	每项为 { name, visualDescription, role?, personalityNotes?, backstoryNotes? }。role 为 protagonist、antagonist、supporting（默认值）或 minor；封面将围绕主角绘制
artStyle	枚举	否	marvel	manga、anime、marvel、dc-comic、comic-noir、franco-belgian、retro-silver-age、webtoon、underground-indie、painted-realism、pixar-3d、hyper-realistic、custom
genre	枚举	否	fantasy	action、adventure、fantasy、sci-fi、horror、romance、mystery、thriller、slice-of-life、superhero、historical、literary
contentRating	枚举	否	teen	all-ages、teen、mature
pageCount	int (4-64)	否	24	目标页数
imageModel	枚举	否	gpt-image-2	同上。创建后锁定
settingDescription	string	否	-	地点、时代、地标。每个分格提示词都会包含此内容
toneNotes、keyScenes、chapterOutline、additionalNotes	string	否	-	用于引导剧本撰写
referenceWorks	string[]	否	-	希望借鉴风格的漫画或电影
aspectRatio	枚举	否	2:3	2:3 或 4:5。创建后锁定
stylePreset	枚举	否	default	气泡样式：default、cartoon-yellow、comic-classic、oblong-classic。创建后锁定

返回： { account, projectId, status, characters: [{ characterId, name, role }], estimate, nextStep }

aetherwave_comic_character_reference

action: "generate" 会以漫画书的风格绘制 count（1-4）张全身参考图，每张消耗 6 点数，并将其添加到角色的选项中。单独使用 editPrompt 可引导全新绘图；将 editPrompt 与 baseUrl（角色的一张图片）搭配使用，则会编辑该图片并保留同一人物。如果调用耗时超过约 50 秒，图片仍会保存到服务端，并显示在 aetherwave_comic_status 中。

action: "approve"（免费）会将 imageUrl 设为参考图。仅接受角色自己的图片或 AetherWave 永久存储（media.aetherwavestudio.com）中的图片。

参数	类型	必填	默认值	说明
projectId	string	是	-
action	enum	是	-	generate 或 approve
characterId 或 characterName	string	二选一	-	匹配名称时不区分大小写
count	int (1-4)	否	1	generate
editPrompt	string (max 500)	否	-	generate
baseUrl	URL	否	-	generate；需要 editPrompt
imageUrl	URL	approve	-

返回值（generate）： { account, characterId, characterName, newImages, creditsCharged, stillGenerating, errors, referenceOptions, nextStep }。返回值（approve）： { account, approved, characterId, characterName, referenceImageUrl }

aetherwave_comic_write_script

开始编写剧本并立即返回。耗时约 2 到 3 分钟；完成后按实际使用量扣费（12 页漫画书需 40 点数）。如果项目已有分格，则拒绝执行，除非设置 replaceExisting: true，因为新剧本会删除所有现有分格。

参数	类型	必填	默认值	说明
projectId	string	是	-
replaceExisting	boolean	否	false	重写已有分格的剧本时必需

返回值： { account, started, status, message, warning?, nextStep }。warning 会列出没有已批准参考图的角色。

aetherwave_comic_draw

action: "start"（默认）会开始逐一绘制所有待处理或失败的分格，并立即返回。每格消耗 9 点数，仅在成功时扣除；开始前余额必须足以支付整个批次。若绘制任务正在运行时调用，则不会开始新任务，并会报告 alreadyDrawing。action: "stop" 会请求当前运行任务在完成当前分格后停止。

参数	类型	必填	默认值	说明
projectId	string	是	-
action	enum	否	start	start 或 stop
maxCredits	int	否	-	start：如果剩余分格的费用会超过此值，则拒绝执行

返回值： { account, started, panelsQueued, creditsPerPanel, upToCredits, message, expectedMinutes, nextStep }，或 { started: false, alreadyDrawing: true }

aetherwave_comic_status

免费。用于查询状态的唯一工具。不提供 projectId 时，会列出你最近的漫画项目。

参数	类型	必填	默认值	说明
projectId	string	否	-	省略则列出项目
detail	enum	否	summary	panels 会列出每个分格（panelId、页码、状态、图片 URL、场景、错误）

返回值： { account, projectId, title, projectStatus, projectError, drawing, drawingDetail, panels: { total, completed, failed, pending, generating, batchRunning }, creditsToFinishDrawing, failedPanels: [{ panelId, page, panelIndex, errorMessage, scene }], pages: { total, assembled, missing, staleSinceAssembly, urls }, characters: [{ characterId, name, role, approvedReference, referenceOptions }], nextStep }

drawing 的值为 no_script、not_started、drawing、redrawing、stalled 或 done。stalled 表示仍有待处理或失败的分格，且当前没有运行任务；请再次调用 aetherwave_comic_draw。

aetherwave_comic_redraw_panel

重绘单个分镜。成功时消耗 9 个点数，失败时不消耗点数。prompt 会替换此次绘图所用的分镜场景描述（保留对白和字幕），可借此绕过内容拒绝。完整任务运行期间无法使用。如果重绘耗时超过约 50 秒，工具会返回 stillDrawing: true，结果会显示在 aetherwave_comic_status 中。

参数	类型	必填	默认值	备注
projectId	string	是	-
panelId	string	是	-	来自 failedPanels 或 detail: "panels"
prompt	string (max 4000)	否	-	新的场景描述

返回： { account, redrawn, panelId, status, imageUrl }、{ redrawn: false, stillDrawing: true }，或包含分镜 errorMessage 的拒绝信息

aetherwave_comic_assemble

免费。为每一页排版并添加文字，每页耗时约 4 秒，完成后立即返回。分镜正在绘制时会拒绝执行；除非设置 allowPartial: true，否则只要有分镜尚未绘制，也会拒绝执行（含有未绘制分镜的页面会被跳过，书籍会标记为 pages-partial）。

参数	类型	必填	默认值	备注
projectId	string	是	-
allowPartial	boolean	否	false	仍然组装完整页面

返回： { account, started, pages, message, nextStep }

aetherwave_comic_export

免费。构建已组装的书籍，并返回 AetherWave 存储中的下载链接，链接有效期约为一天。通常会在调用期间完成（测试中，构建并上传一份 12 页的 PDF 耗时约 15 秒）；否则会返回 exportId，可通过第二次调用查询。同一账户一次只能构建一个导出文件：如果已有导出任务正在构建，工具会报告该任务（alreadyExporting: true，并附带其 projectId），而不会另行启动。当服务繁忙时，工具会拒绝请求并返回 retryAfterSeconds。

参数	类型	必填	默认值	备注
projectId	string	是	-
format	enum	否	pdf	pdf、epub（固定版式，适用于 Kindle）、cbz、bundle（包含以上三种格式及页面 PNG）
includeBackMatter	boolean	否	true	如果已启用，则在末尾附加项目的宣传页
exportId	string	否	-	查询之前启动的导出任务

返回： { account, exportId, format, status, url, megabytes, note }。status 为 building、complete 或 error。

点数与定价

AetherWave 使用统一点数池。可购买套餐，起价为 $4.99 / 500 点数（套餐点数永不过期）；也可订阅 Studio（$9.99/mo，1,700 点数；没有免费试用，注册时开始计费）。两者都可用于 API 调用。

常见费用：

• 图像生成 - 2 点（Z-Image Turbo）至 34 点（4K 高级模型）；默认生成 2 张图时为 6 点
• 图像编辑 - 6 至 34 点；默认 10 点（Grok Imagine I2I）
• 图像工具 - 4 点（放大 2 倍或 4 倍）、5 点（移除背景）、5 / 10 / 14 点（按速度调整画幅）
• 视频 - 每秒 4 点（Grok Imagine，480p）至每秒 143 点（Seedance 2，1080p）；VEO 3.1 每段 8 秒视频固定收费 42 / 84 / 350 点
• 音乐 - 每次生成 20 点（2 首曲目）
• 母带处理 - 每首曲目 20 点（Artist / Producer / Mogul / Ultimate 套餐免费）
• 漫画书 - 每个分镜 9 点（成功时扣费），每个角色参考图 6 点，按使用量收取脚本费用（12 页约 40 点）。一本 12 页、27 个分镜的漫画书共花费 301 点

请访问 https://aetherwavestudio.com/buy-credits 或通过 aetherwave_list_*_models 查看实时价格。

环境变量

变量	必填	默认值	描述
AETHERWAVE_API_KEY	是	-	你的 API 密钥。在 /profile -> Developer 选项卡中获取。必须以 aw_live_ 开头。
AETHERWAVE_BASE_URL	否	https://aetherwavestudio.com	覆盖 API 基础 URL（适用于暂存环境或可自托管环境）。

故障排除

“需要设置 AETHERWAVE_API_KEY 环境变量” 你的 MCP 客户端没有传递环境变量。请确保客户端配置中的 env 块已设置 AETHERWAVE_API_KEY。编辑配置后，请完全重启客户端。

“AetherWave API ... 失败：401 - API 密钥无效” 该密钥已被撤销或重新生成。访问 https://aetherwavestudio.com/profile -> Developer 标签页，并复制新密钥。

“AetherWave API ... 失败：402 - 额度不足” 你的余额不足以完成所请求的操作。调用 aetherwave_balance 确认余额，然后前往 https://aetherwavestudio.com/buy-credits 充值。

“AetherWave 生成在 X 秒后超时” 提供方正在排队处理。任务可能仍会在服务端完成——请查看 AetherWave 画廊：https://aetherwavestudio.com/gallery.html。如果某个模型持续超时，请尝试其他模型（例如，从 grok-imagine-t2v 切换到 wan-2-7-t2v，或从 gpt-image-1.5-i2i 切换到 grok-imagine-i2i）。

reframe 返回“无法处理的实体” Ideogram 的 URL 抓取器无法处理包含空格、括号或其他特殊字符的源 URL。请使用干净的 URL（如有需要，可尝试下载文件并重新上传到干净的 R2 路径）。

remove_background 返回“内部错误，请稍后重试” KIE Recraft 暂时发生故障。重试时，该工具会自动回退到 fal.ai BiRefNet v2，但如果单次调用返回此错误，说明两个提供方都拒绝了请求。请等待一分钟后重试。

漫画状态显示 drawing: "stalled" 绘制任务已结束，但仍有分镜未完成：可能是服务重启、余额耗尽或任务被停止。再次调用 aetherwave_comic_draw；它只会绘制缺失的分镜，并且只对成功的分镜收费。

漫画分镜反复因“可能违反我们的内容政策”而失败 对同一场景重试会得到相同的拒绝结果。请使用新的 prompt，通过 aetherwave_comic_redraw_panel 重新措辞。即使是全年龄向的书籍，也不允许描写成人与儿童之间的身体接触。

aetherwave_comic_export 提示服务器“尚不支持导出链接” 你所连接的 AetherWave 服务版本早于导出链接功能。请在 Web 应用的 Graphic Novel Studio 中下载该书。

Soul Forge 乐队生成 未通过 MCP 提供。Soul Forge 仍是网页上的消费者功能：https://aetherwavestudio.com/soul-forge。

版本管理

此软件包遵循 semver。会以不兼容方式改变行为的工具将提升主版本号。新增工具和增量参数将提升次版本号。错误修复将提升补丁版本号。

0.3.1（未发布）：aetherwave_upload_to_gallery 和 aetherwave_get_user_manual，默认提供 33 个工具。

0.3.0（2026-09-30）：所有长时间运行的工具都设置了 45 秒软截止时间（返回 state: "running" + taskId，而不是让客户端超时），所有工具都支持 async: true，aetherwave_get_job 覆盖所有流水线，9 个漫画工具，4 个周边商品工具（+2 个需要 PRINTFUL_API_TOKEN 的 Printful 工具，+1 个管理工具），默认提供 31 个工具。

MCP 协议本身的版本（目前为 2024-11-05）由 SDK 在握手时协商；无需客户端配置。

链接

• AetherWave Studio：https://aetherwavestudio.com
• 开发者文档：https://aetherwavestudio.com/developers
• 获取 API 密钥：https://aetherwavestudio.com/profile（Developer 标签页）
• 购买额度：https://aetherwavestudio.com/buy-credits
• GitHub：https://github.com/AetherWave-Studio/aetherwave-mcp
• npm：https://www.npmjs.com/package/@aetherwave-studio/mcp

许可证

MIT。请参阅 LICENSE。