retrodiffusion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Retro Diffusion — True Pixel Art Generation

Retro Diffusion — 真实像素艺术生成

Generate authentic pixel art sprites, tilesets, and animations from text prompts or reference images using the Retro Diffusion API. Output is true pixel art (clean integer-pixel grids, limited palettes), not blurry diffusion-model output downscaled into pixels — making it the best AI option for shippable 2D game art and fast prototyping.

Paid service. Retro Diffusion requires an account at https://www.retrodiffusion.ai and an API key with credits. Always tell the user this requires a paid Retro Diffusion account before generating anything, and confirm they understand each call deducts from their balance.

借助Retro Diffusion API，通过文本提示词或参考图生成真实的像素艺术精灵图、瓦片集和动画。输出的是真实像素艺术（清晰的整数像素网格、有限调色板），并非模糊的扩散模型输出缩小为像素——这使其成为可发布2D游戏美术和快速原型制作的最佳AI选择。

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

Reference Files

参考文件

File	Description
api-reference.md	Full API endpoints, models, prompt_style values, response shape, pricing, and error codes

文件	描述
api-reference.md	完整的API端点、模型、prompt_style取值、响应格式、定价及错误码

When to Use

使用场景

Quick prototypes — generate dozens of unique sprites in a minute instead of hand-coding 16×16 arrays
Polish pass on a working game — replace placeholder shapes with cohesive pixel art that already matches a chosen style
Tilesets — wang-style ground/wall sets without manually drawing every transition tile
Sprite animations — walk cycles, idle bobs, attacks delivered as transparent GIFs or spritesheets

Choose this over
add-assets
(code-only pixel art) when: the user wants AI-generated art, has a Retro Diffusion key, or the game needs more visual variety than hand-coded matrices can deliver in a reasonable time. The two skills compose well — Retro Diffusion for hero sprites/tilesets, code-only matrices as a free fallback for quick filler.

Do NOT use this for: 3D models (use

meshyai

), 3D worlds (use

worldlabs

), audio (use

game-audio

), or when the user explicitly wants the all-code procedural pixel art approach (use

add-assets

快速原型制作 — 一分钟内生成数十个独特精灵图，无需手动编写16×16像素数组
完善成品游戏 — 用风格统一的像素艺术替换占位图形，且风格已匹配预设要求
瓦片集 — 无需手动绘制每个过渡瓦片，生成Wang风格的地面/墙面集
精灵动画 — 提供行走循环、 idle动作、攻击动画，输出为透明GIF或精灵图序列

当以下情况时，优先选择本工具而非
add-assets
（纯代码像素艺术）：用户需要AI生成的美术资源、拥有Retro Diffusion密钥，或游戏需要比手动编写像素矩阵在合理时间内更丰富的视觉多样性。这两个工具可配合使用——Retro Diffusion用于主角精灵图/瓦片集，纯代码矩阵作为免费备选方案快速生成填充资源。

请勿用于：3D模型（使用

meshyai

）、3D世界（使用

worldlabs

）、音频（使用

game-audio

），或用户明确要求全代码 procedural像素艺术的场景（使用

add-assets

）。

Authentication

身份验证

Before prompting the user, check if the key already exists:

bash

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

If found, export it with

set -a; . .env; set +a

and skip the prompt.

If the key is not set, ask the user immediately and explain the cost model:

I'll generate true pixel art with Retro Diffusion — the best dedicated pixel art model for shippable game sprites.

Heads up: this is a paid service. You'll need a Retro Diffusion account with credits. Each image typically costs between $0.015 (RD_FAST) and $0.18 (RD_PRO). Get a key in 60 seconds:

Sign up at https://www.retrodiffusion.ai

Buy credits (smallest pack is fine for prototyping)

Account → API → Generate API key
Paste your key like:
RETRODIFFUSION_API_KEY=rdpk-...
(It will be saved to
.env
and redacted from this conversation.)
Or type "skip" to fall back to free hand-coded pixel art via
/add-assets
.

If the user provides a key, save it to

.env

and use it via

set -a; . .env; set +a && node scripts/retrodiffusion-generate.mjs ...

If the user skips, stop and hand off to
/add-assets
— do not silently degrade to a different art style without telling them.

在提示用户前，先检查密钥是否已存在：

bash

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

若已找到，执行

set -a; . .env; set +a

导出密钥，跳过提示步骤。

若密钥未设置，立即询问用户并解释收费模式：

我将使用Retro Diffusion生成真实像素艺术——这是可发布游戏精灵图的最佳专用像素艺术模型。

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

在https://www.retrodiffusion.ai注册账户

购买 credits（最小套餐即可满足原型制作需求）

进入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 Script —

scripts/retrodiffusion-generate.mjs

CLI脚本 —

scripts/retrodiffusion-generate.mjs

Zero-dependency Node.js script. Handles all six modes: generate, img2img, animate, tileset, edit, and balance.

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

Generate (text-to-pixel-art)

生成（文本转像素艺术）

bash

undefined

bash

undefined

Single 64×64 sprite, RD_FAST (cheapest)

单张64×64精灵图，使用RD_FAST（成本最低）

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)

使用RD_PRO生成更高质量的图（固定$0.18，支持最大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

undefined

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs
--mode generate --prompt "..." --check-cost

undefined

Image-to-Image (refine a reference)

图生图（优化参考图）

bash

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

controls how much the AI deviates from the input (0 = identical, 1 = ignore input). 0.5–0.8 is the useful range.

bash

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为实用范围。

Animations (walk cycles, idles, attacks)

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

bash

undefined

bash

undefined

Walk cycle — returns spritesheet PNG or transparent GIF (style-dependent)

行走循环 — 返回精灵图序列PNG或透明GIF（取决于风格）

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

基于现有角色生成idle晃动动画

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


Animation styles cost $0.07–$0.25 depending on type. See [api-reference.md](./api-reference.md) for the full style list.


动画风格的成本为$0.07–$0.25，具体取决于类型。完整风格列表请查看[api-reference.md](./api-reference.md)。

Tilesets

瓦片集

bash

undefined

bash

undefined

Wang-style tileset (auto-tiling ground/wall sets)

Wang风格瓦片集（自动拼接的地面/墙面集）

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

undefined

undefined

Edit (progressive refinement)

编辑（渐进式优化）

Flat $0.06 per edit. Use to tweak a generated sprite without re-rolling from scratch.

bash

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

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

bash

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

Balance check

余额查询

bash

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

bash

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

Model Selection Guide

模型选择指南

Model	Cost	Sizes	Best for
RD_FAST	$0.015–0.04	64×64 to 384×384	Bulk prototyping, simple sprites, items
RD_PLUS	$0.025–0.08	16×16 to 192×192	Tilesets, top-down, watercolor, Minecraft-style
RD_PRO	$0.18 flat	64×64 to 256×256	Hero sprites, isometric scenes, polish pass (17+ styles, supports up to 9 reference images)
RD_MINI	varies	very small	Routes to PLUS/FAST for tiny pickups

Default to RD_FAST for prototyping. Upgrade individual hero sprites to RD_PRO when the prototype is shipping.

See api-reference.md for the complete per-model

prompt_style

list.

模型	成本	尺寸	最佳用途
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。

Prompt Engineering for Pixel Art

像素艺术提示词技巧

Good prompts are short, specific about silhouette and palette, and call out the perspective:

Goal	Prompt	Why
Game character	"a cute green slime, big eyes, side view"	Single subject, perspective named
Item	"a glowing red potion bottle"	Specific shape + color
Tile	"lush grass texture, top down, seamless"	Perspective + tiling intent
Enemy	"a skeleton warrior, hunched, side view"	Silhouette cue ("hunched")

Avoid:

Multiple subjects in one prompt — generate separately and composite in-game
Abstract concepts ("the feeling of dread") — describe the visual instead
Mismatched perspective ("top-down knight, side view") — pick one

优秀的提示词应简洁，明确轮廓和调色板，并指定视角：

目标	提示词	原因
游戏角色	"a cute green slime, big eyes, side view"	单一主体，明确视角
道具	"a glowing red potion bottle"	明确形状+颜色
瓦片	"lush grass texture, top down, seamless"	明确视角+平铺需求
敌人	"a skeleton warrior, hunched, side view"	包含轮廓提示（"hunched"）

避免：

单个提示词包含多个主体——分开生成后在游戏中合成
抽象概念（"the feeling of dread"）——改为描述视觉元素
视角冲突（"top-down knight, side view"）——仅选择一个视角

Integration with Phaser Games

与Phaser游戏集成

Retro Diffusion outputs are normal PNGs — they slot directly into Phaser's loader.

// 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,
});

Pixel-perfect rendering — when using AI pixel art, configure the Phaser game with crisp scaling so sprites stay sharp:

// 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 },
  // ...
};

Without

pixelArt: true

, the browser will smooth-scale the PNGs and the pixel-art look is lost.

Retro Diffusion的输出为标准PNG，可直接导入Phaser的加载器。

// 在预加载场景中：
this.load.image('slime', 'assets/sprites/slime.png');
this.load.spritesheet('knight-walk', 'assets/sprites/knight-walk.png', {
  frameWidth: 64,
  frameHeight: 64,
});

// 在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游戏启用清晰缩放，确保精灵图保持锐利：

// 在main.js的Phaser配置中：
const config = {
  type: Phaser.AUTO,
  pixelArt: true,           // 禁用抗锯齿，保留清晰像素边缘
  roundPixels: true,        // 将精灵图位置对齐到整数像素
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  // ...
};

若未设置

pixelArt: true

，浏览器会平滑缩放PNG，导致像素艺术风格丢失。

Spritesheet Slicing

精灵图序列切片

Animation styles return either a transparent GIF or a horizontal spritesheet (style-dependent — check the output PNG dimensions). For spritesheets, infer

frameWidth = imageWidth / frameCount

and load with

this.load.spritesheet()

. The

.meta.json

file written next to each output records the requested width/height so frame count is recoverable.

动画风格的输出为透明GIF或水平精灵图序列（取决于风格——请检查输出PNG的尺寸）。对于精灵图序列，可通过

frameWidth = imageWidth / frameCount

计算单帧宽度，再用

this.load.spritesheet()

加载。每个输出文件旁的

.meta.json

记录了请求的宽度/高度，可据此恢复帧数。

Cost Discipline

成本管控

Every call costs real money from the user's balance. Apply these defaults to avoid waste:

Use
--check-cost
first when generating at unfamiliar sizes or with RD_PRO.
Default to RD_FAST + 64×64 for prototypes. Only upgrade specific hero sprites.
Use
--seed
when iterating on a prompt — same seed + same prompt = same image, so you can A/B test prompt edits without re-rolling random variations.
Cache outputs — generated PNGs are committed to
```
public/assets/sprites/
```
. Never regenerate an asset that already exists unless the user asked for a new variant.
Run
--mode balance
before a big batch so the user sees their remaining credits.

每次调用都会消耗用户账户的真实资金。请遵循以下默认规则避免浪费：

**首次使用陌生尺寸或RD_PRO时，先使用
```
--check-cost
```
**估算成本。
原型制作默认使用RD_FAST + 64×64。仅针对特定主角精灵图升级模型。
迭代提示词时使用
--seed
——相同seed+相同提示词=相同图像，可对比提示词修改效果，无需生成随机变体。
缓存输出——生成的PNG会保存到
```
public/assets/sprites/
```
。除非用户要求新变体，否则不要重新生成已存在的资源。
批量生成前执行
--mode balance
，让用户查看剩余 credits。

Output Convention

输出规范

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

Always write a

.meta.json

next to each PNG so the prompt and seed are recoverable for later regeneration.

public/assets/sprites/
  slime.png            # 生成的图片
  slime.meta.json      # 提示词、模型、风格、成本、余额、时间戳
  knight-walk.png      # 动画精灵图序列或GIF
  knight-walk.meta.json
public/assets/tiles/
  grass.png            # 平铺纹理
  grass.meta.json

务必在每个PNG旁生成

.meta.json

，以便后续重新生成时恢复提示词和seed。

Troubleshooting

故障排查

Problem	Cause	Fix
`RETRODIFFUSION_API_KEY` not set	Key missing	Ask the user for their key (https://www.retrodiffusion.ai → Account → API). Save to `.env` .
HTTP 401 Unauthorized	Wrong header or invalid key	Header must be `X-RD-Token: <key>` , NOT `Authorization: Bearer` . Verify the key on the dashboard.
HTTP 400 "insufficient credits"	Account balance is empty	Tell the user to top up at the dashboard before retrying. Run `--mode balance` to confirm.
Sprite looks blurry in Phaser	Browser is smooth-scaling the PNG	Set `pixelArt: true` and `roundPixels: true` in the Phaser config.
Output ignores prompt details	Prompt is being auto-expanded into something different	Try `--bypass-prompt-expansion` to send the prompt verbatim.
Tileset edges don't match	Style isn't a wang/tile style	Use `--style wang-tile` for auto-tiling sets, or `--tile-x --tile-y` for seamless single textures.
img2img output ignores reference	Strength too high	Lower `--strength` to 0.4–0.6. Strength 0 keeps the input; strength 1 ignores it.
Inconsistent style across batch	Different seeds and slight prompt variation	Pin `--seed` and reuse the exact same prompt structure for sibling sprites (same character family).

问题	原因	解决方法
`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/tile风格	使用 `--style wang-tile` 生成自动拼接瓦片集，或使用 `--tile-x --tile-y` 生成无缝单张纹理。
图生图输出忽略参考图	strength值过高	将 `--strength` 降低至0.4–0.6。strength为0时保留原图；为1时忽略原图。
批量生成风格不一致	seed不同且提示词略有差异	固定 `--seed` ，并为同系列精灵图（如同一角色的不同动作）使用完全相同的提示词结构。

Checklist

检查清单

User informed this is a paid service — Retro Diffusion account + credits required
```
RETRODIFFUSION_API_KEY
```
checked in
```
.env
```
or env, prompted if missing
Model + style chosen for the budget (RD_FAST for prototyping, RD_PRO for hero sprites)
```
--check-cost
```
used for the first call at any new size
Prompt is specific about subject, perspective, and silhouette
```
--seed
```
pinned when generating siblings (e.g., walk + idle of the same character)
```
--remove-bg
```
used for game sprites (transparent PNG)
```
--tile-x
```
/
```
--tile-y
```
used for textures,
```
--style wang-tile
```
for auto-tiling
PNG written to
```
public/assets/sprites/
```
(or
```
tiles/
```
) with
```
.meta.json
```
alongside
Phaser config has
```
pixelArt: true
```
and
```
roundPixels: true
```
Spritesheet
```
frameWidth
```
/
```
frameHeight
```
matches the requested width/height
User shown remaining balance after the batch

已告知用户这是付费服务——需要Retro Diffusion账户+可用 credits
已检查
```
.env
```
或环境变量中的
```
RETRODIFFUSION_API_KEY
```
，缺失时已提示用户
根据预算选择了合适的模型+风格（原型用RD_FAST，主角精灵图用RD_PRO）
首次使用新尺寸时已用
```
--check-cost
```
估算成本
提示词明确了主体、视角和轮廓
生成同系列资源（如同一角色的行走+idle动画）时已固定
```
--seed
```
生成游戏精灵图时已使用
```
--remove-bg
```
（透明PNG）
生成纹理时已使用
```
--tile-x
```
/
```
--tile-y
```
，生成自动拼接瓦片集时已使用
```
--style wang-tile
```
PNG已保存到
```
public/assets/sprites/
```
（或
```
tiles/
```
），且旁附
```
.meta.json
```
Phaser配置已设置
```
pixelArt: true
```
和
```
roundPixels: true
```
精灵图序列的
```
frameWidth
```
/
```
frameHeight
```
与请求的宽度/高度匹配
批量生成后已告知用户剩余余额