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	出力スプライトのサイズ（px）	128
-r	生成解像度（1K/2K）	1K
-d	フレームの表示時間（ms）	100
--two-step	最初にピクセル化し、その後アニメーション化します（写真に適しています）	オフ
--keep-sheet	元のスプライトシートを保存します	オフ
--keep-frames	個別のフレーム PNG を保存します	オフ

ヒント

• 実在する人物の写真には --two-step を使用してください。そうしないと、Gemini は元の人物らしさを再現できません
• 品質を大幅に向上させるには -r 2K を使用してください
• より自然な再生速度にするには -d 180 を使用してください（デフォルトの 100ms は速めです）
• 出来の良いベースのピクセルアートスプライトを保存して、別のアニメーションにも再利用してください
• Telegram では、MP4 への変換を避けるため、GIF をドキュメントとして送信してください

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)