retrodiffusion

Retro Diffusion — 真正的像素艺术生成

使用 Retro Diffusion API，根据文本提示词或参考图像生成原汁原味的像素艺术精灵、图块集和动画。输出是真正的像素艺术（整洁的整数像素网格、有限的调色板），而不是将模糊的扩散模型输出缩小成像素图——因此，它是制作可用于发布的 2D 游戏美术和快速原型的最佳 AI 选择。

付费服务。 Retro Diffusion 需要在 https://www.retrodiffusion.ai 注册账户，并准备好有余额的 API 密钥。生成任何内容前，务必告知用户这需要付费的 Retro Diffusion 账户，并确认他们了解每次调用都会扣除余额。

参考文件

文件	描述
api-reference.md	完整的 API 端点、模型、prompt_style 值、响应结构、价格和错误代码

适用场景

• 快速原型 — 一分钟内生成数十个独特精灵，而不用手动编写 16×16 数组
• 为可运行的游戏润色 — 用风格统一、符合所选风格的像素艺术替换占位图形
• 图块集 — 生成 wang 风格的地面／墙壁图块集，无需手动画出每一块过渡图块
• 精灵动画 — 行走循环、待机动作、攻击动画，以透明 GIF 或精灵图集的形式交付

在以下情况中，相比 add-assets（纯代码像素艺术）优先选择此工具： 用户想要 AI 生成的美术资源、拥有 Retro Diffusion 密钥，或游戏需要的视觉多样性超出了手写矩阵在合理时间内能实现的程度。这两种技能也很适合组合使用——用 Retro Diffusion 生成主角精灵／图块集，用纯代码矩阵作为免费方案，快速填充其他素材。

请勿用于： 3D 模型（使用 meshyai）、3D 世界（使用 worldlabs）、音频（使用 game-audio），或用户明确要求采用纯代码程序化像素艺术方案时（使用 add-assets）。

身份验证

询问用户前，检查密钥是否已存在：

test -f .env && grep -q '^RETRODIFFUSION_API_KEY=.' .env && echo "found"

如果找到密钥，使用 set -a; . .env; set +a 导出，并跳过询问。

如果未设置密钥，立即询问用户，并说明费用模式：

我将使用 Retro Diffusion 生成真正的像素艺术——这是专为制作可用于发布的游戏精灵而打造的最佳像素艺术模型。

请注意：这是一项付费服务。 你需要拥有一个有余额的 Retro Diffusion 账户。每张图像的费用通常在 $0.015（RD_FAST）到 $0.18（RD_PRO）之间。只需 60 秒即可获取密钥：

1. 在 https://www.retrodiffusion.ai 注册
2. 购买余额（原型制作使用最小套餐即可）
3. 进入 Account → API → Generate API key

粘贴密钥，格式如下：RETRODIFFUSION_API_KEY=rdpk-... （密钥将保存到 .env，并在此对话中隐藏。）

或输入“skip”，改用 /add-assets 通过手写代码免费生成像素艺术。

如果用户提供了密钥，将其保存到 .env，并使用 set -a; . .env; set +a && node scripts/retrodiffusion-generate.mjs ... 调用。

如果用户跳过，停止并转交给 /add-assets——不要在未告知用户的情况下悄悄改用其他美术风格。

CLI 脚本 — scripts/retrodiffusion-generate.mjs

零依赖的 Node.js 脚本。支持全部六种模式：生成、图生图、动画、图块集、编辑和余额查询。

生成（文本转像素艺术）

# Single 64×64 sprite, RD_FAST (cheapest)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a cute green slime with big eyes" \
  --model RD_FAST --style retro \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug slime

# Higher quality with RD_PRO (flat $0.18, supports up to 256×256)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a heroic knight, full body, side view" \
  --model RD_PRO --style fantasy \
  --width 128 --height 128 \
  --output public/assets/sprites/ --slug knight

# Transparent background for game sprites
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "a treasure chest, closed" \
  --model RD_FAST --style game-asset \
  --width 64 --height 64 --remove-bg \
  --output public/assets/sprites/ --slug chest

# Seamless tiling texture (e.g., grass, water)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "lush grass texture, top down" \
  --model RD_PLUS --style top-down \
  --width 64 --height 64 --tile-x --tile-y \
  --output public/assets/tiles/ --slug grass

# Estimate cost before paying for it
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "..." --check-cost

图像转图像（优化参考图）

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode img2img \
  --image ./concept-art/hero-sketch.png \
  --prompt "a heroic knight in shining armor" \
  --model RD_FAST --style retro \
  --width 64 --height 64 --strength 0.75 \
  --output public/assets/sprites/ --slug hero

--strength 用于控制 AI 对输入图像的偏离程度（0 = 完全一致，1 = 忽略输入）。0.5–0.8 是实用范围。

动画（行走循环、待机动作、攻击）

# Walk cycle — returns spritesheet PNG or transparent GIF (style-dependent)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate \
  --prompt "a knight walking" \
  --model RD_PRO --style walk-cycle \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug knight-walk

# Idle bob from an existing character
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate --image public/assets/sprites/knight.png \
  --prompt "knight idle breathing" --style idle \
  --output public/assets/sprites/ --slug knight-idle

动画样式的费用为 $0.07–$0.25，具体取决于类型。完整样式列表请参阅 api-reference.md。

图块集

# Wang-style tileset (auto-tiling ground/wall sets)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset \
  --prompt "stone dungeon floor, mossy" \
  --model RD_PLUS --style wang-tile \
  --width 96 --height 96 \
  --output public/assets/tiles/ --slug dungeon-floor

# Single detailed tile
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset --prompt "wooden bridge plank" --style single-tile \
  --width 64 --height 64 --output public/assets/tiles/ --slug bridge

编辑（渐进式优化）

每次编辑固定收费 $0.06。可用于微调已生成的精灵，而无需从头重新生成。

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode edit --image public/assets/sprites/knight.png \
  --prompt "give the knight a red cape" \
  --output public/assets/sprites/ --slug knight-red

余额查询

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs --mode balance

模型选择指南

模型	费用	尺寸	最适合的用途
RD_FAST	$0.015–0.04	64×64 到 384×384	批量原型制作、简单精灵、物品
RD_PLUS	$0.025–0.08	16×16 到 192×192	瓦片集、俯视视角、水彩风格、Minecraft 风格
RD_PRO	固定 $0.18	64×64 到 256×256	主角精灵、等距场景、润色（17 种以上风格，最多支持 9 张参考图）
RD_MINI	不固定	非常小	处理微型拾取物时转用 PLUS/FAST

原型制作默认使用 RD_FAST。原型准备发布时，再将个别主角精灵升级为 RD_PRO。

完整的各模型 prompt_style 列表请参见 api-reference.md。

像素艺术的提示词工程

好的提示词应简短，明确描述轮廓和调色板，并指出视角：

目标	提示词	原因
游戏角色	“一个可爱的绿色史莱姆，大眼睛，侧视图”	单一主体，明确指定视角
物品	“一个发光的红色药水瓶”	明确的形状和颜色
瓦片	“繁茂的草地纹理，俯视视角，无缝衔接”	明确视角和拼接意图
敌人	“一个驼背的骷髅战士，侧视图”	轮廓提示（“驼背”）

避免：

• 在一个提示词中描述多个主体——分别生成，再在游戏中合成
• 抽象概念（“恐惧感”）——改为描述具体视觉效果
• 视角不一致（“俯视的骑士，侧视图”）——选定一种视角

与 Phaser 游戏集成

Retro Diffusion 输出的是普通 PNG，可直接交由 Phaser 的加载器加载。

// In a preload scene:
this.load.image('slime', 'assets/sprites/slime.png');
this.load.spritesheet('knight-walk', 'assets/sprites/knight-walk.png', {
  frameWidth: 64,
  frameHeight: 64,
});

// In create():
const slime = this.physics.add.sprite(100, 100, 'slime');
this.anims.create({
  key: 'knight-walk',
  frames: this.anims.generateFrameNumbers('knight-walk', { start: 0, end: 7 }),
  frameRate: 12,
  repeat: -1,
});

像素完美渲染——使用 AI 像素艺术时，请为 Phaser 游戏配置清晰缩放，让精灵保持锐利：

// In main.js, Phaser config:
const config = {
  type: Phaser.AUTO,
  pixelArt: true,           // disables antialiasing, preserves hard pixel edges
  roundPixels: true,        // snaps sprite positions to integers
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  // ...
};

如果没有设置 pixelArt: true，浏览器会对 PNG 进行平滑缩放，像素艺术的效果也会随之消失。

精灵图集切片

动画风格会输出透明 GIF 或水平排列的精灵图集（取决于风格——请检查输出 PNG 的尺寸）。对于精灵图集，请推算 frameWidth = imageWidth / frameCount，并使用 this.load.spritesheet() 加载。每个输出文件旁生成的 .meta.json 文件会记录请求的宽度和高度，因此可以还原帧数。

费用控制

每次调用都会实际扣除用户余额中的费用。请采用以下默认做法以避免浪费：

1. 以不熟悉的尺寸生成内容或使用 RD_PRO 时，先运行 --check-cost。
2. 原型制作默认使用 RD_FAST + 64×64。仅升级特定的主角精灵。
3. 迭代提示词时使用 --seed——相同种子和相同提示词会生成相同图像，因此无需重新随机生成，就可以对提示词修改进行 A/B 测试。
4. 缓存输出——生成的 PNG 会提交到 public/assets/sprites/。除非用户要求新变体，否则绝不重新生成已有资源。
5. 批量生成前运行 --mode balance，让用户查看剩余点数。

输出规范

public/assets/sprites/
  slime.png            # generated image
  slime.meta.json      # prompt, model, style, cost, balance, timestamps
  knight-walk.png      # animation spritesheet or GIF
  knight-walk.meta.json
public/assets/tiles/
  grass.png            # tiling texture
  grass.meta.json

始终在每个 PNG 旁写入一个 .meta.json，以便之后恢复提示词和种子并重新生成。

故障排除

问题	原因	修复方法
未设置 RETRODIFFUSION_API_KEY	缺少密钥	请用户提供密钥（https://www.retrodiffusion.ai → Account → API）。保存到 .env。
HTTP 401 Unauthorized	请求头错误或密钥无效	请求头必须是 X-RD-Token: <key>，不能是 Authorization: Bearer。在控制面板中验证密钥。
HTTP 400 "insufficient credits"	账户余额为零	告知用户先在控制面板充值，再重试。运行 --mode balance 进行确认。
Phaser 中的精灵看起来模糊	浏览器对 PNG 进行了平滑缩放	在 Phaser 配置中设置 pixelArt: true 和 roundPixels: true。
输出忽略提示词的细节	提示词被自动扩展成了其他内容	尝试使用 --bypass-prompt-expansion，逐字发送提示词。
瓦片集边缘不匹配	样式不是 wang/瓦片样式	自动拼接瓦片集请使用 --style wang-tile，无缝单张纹理请使用 --tile-x --tile-y。
img2img 输出忽略参考图	强度过高	将 --strength 降至 0.4–0.6。强度为 0 时保留输入图像；强度为 1 时忽略输入图像。
批量生成的风格不一致	随机种子不同，且提示词略有差异	固定 --seed，并为同系列精灵重用完全相同的提示词结构（例如同一角色的不同精灵）。

检查清单

• 已告知用户这是一项付费服务 — 需要 Retro Diffusion 账户和点数
• 已在 .env 或环境变量中检查 RETRODIFFUSION_API_KEY；缺少时已提示用户提供
• 已根据预算选择模型和样式（原型制作使用 RD_FAST，主角精灵使用 RD_PRO）
• 首次调用任何新尺寸时使用了 --check-cost
• 提示词具体说明了主体、透视和轮廓
• 生成同系列精灵时固定了 --seed（例如同一角色的行走和待机状态）
• 游戏精灵使用了 --remove-bg（透明 PNG）
• 纹理使用了 --tile-x/--tile-y；自动拼接使用了 --style wang-tile
• PNG 已写入 public/assets/sprites/（或 tiles/），并在旁边放置了 .meta.json
• Phaser 配置包含 pixelArt: true 和 roundPixels: true
• Spritesheet 的 frameWidth/frameHeight 与请求的宽度/高度一致
• 已向用户展示批量生成后的剩余余额