sprite-animator

Sprite Animator

将任意图片转换为像素艺术动画 GIF。使用 Gemini 图像生成创建 16 帧精灵表，然后将其组装成循环播放的 GIF。

要求

• 必须设置 GEMINI_API_KEY 或 GOOGLE_API_KEY 环境变量
• 安装：uv tool install sprite-animator（或使用 uvx sprite-animator 运行一次性任务）

快速使用

# Best quality for photos — two-step converts to pixel art first, then animates
sprite-animator -i photo.png -o dance.gif -a dance --two-step -s 256 -r 2K

# From drawings or pixel art (single step is fine)
sprite-animator -i drawing.png -o idle.gif -a idle -s 256 -r 2K

动画类型

• idle — 轻柔呼吸并眨眼（默认）
• wave — 抬臂 → 挥手 → 回到原位
• bounce — 蹲下 → 跳起 → 落地
• dance — 倾斜、旋转、跳跃 — 尽情狂欢

关键选项

标志	说明	默认值
-i	输入图片路径	必填
-o	输出 GIF 路径	必填
-a	动画类型（idle/wave/bounce/dance）	idle
-s	输出精灵尺寸（像素）	128
-r	生成分辨率（1K/2K）	1K
-d	帧时长（毫秒）	100
--two-step	先进行像素化，再制作动画（更适合照片）	关闭
--keep-sheet	保存原始精灵表	关闭
--keep-frames	保存单独的帧 PNG	关闭

提示

• 对真人照片使用 --two-step —— 否则 Gemini 会丢失人物相似度
• 使用 -r 2K 可显著提升画质
• 使用 -d 180 可获得更自然的播放速度（默认 100ms 较快）
• 保存效果好的基础像素艺术精灵，以便用于不同动画
• 在 Telegram 上将 GIF 作为文件发送，以避免转换为 MP4

Python API

from pathlib import Path
from PIL import Image
from sprite_animator.cli import ANIMATION_PRESETS, generate_sprite_sheet, create_gif, call_gemini, get_api_key
from sprite_animator.template import create_template, extract_frames

api_key = get_api_key()
preset = ANIMATION_PRESETS["dance"]

# Create template and generate sprite sheet
template = create_template(cols=4, rows=4, labels=preset["labels"])
template.save("template.png")

generate_sprite_sheet(
    api_key=api_key,
    input_image=Image.open("input.png"),
    template_path=Path("template.png"),
    output_path=Path("sheet.png"),
    prompt=preset["prompt"],
    resolution="2K",
)

# Extract frames and build GIF
frames = extract_frames(Image.open("sheet.png"), cols=4, rows=4)
create_gif(frames, Path("output.gif"), frame_duration=180, size=256)