Meowart Game Asset
快速入口
- 需要先判断用哪个命令、参数怎么写、输出会落到哪里时，先读
meowart_api.md。 - 需要确认精确 CLI 参数、请求结构、轮询逻辑、下载逻辑，或者准备扩展脚本时，直接读
meowart_api.py。 - 需要快速执行资产生成任务时，先看下面的“核心规则”，再按后文的“实战指南”选择具体工作流。
AI生图基础
- 基本原理：
- 原理一：输出的图片的各个位置的画风可以做到非常一致，但是不一定能够和输入图一致（输出的各个位置本质上还在一个图上，而输入是经过了深度网络转换）。 - 原理二：VLM通常有一些默认的输出尺寸，如果输入尺寸和这些尺寸不一致可能有隐含的形变（缩放，裁剪），会产生一些意料之外的情况，尽量避免。
- 常用方法：保证输入和输出相同尺寸，且让参考图和生成的图在一张图上，这样不仅可以严格控制风格一致性，也能精准修改画面的指定位置。
- 留白生成：在参考图中放上数个参考对象，并留出空白，通过 prompt 引导大模型在空白处生成新的对象。这样确保了参考对象和生成的对象出现在一张画布。基于原理一，这可以让生成的对象的风格严格和参考对象一致。 - 批量生成：一次性生成 N 个对象，由于这 N 个对象在一张画布上，基于原理一，因此也能确保彼此的风格是一致的。 - 轮廓生成：先用 python 或者让用户在图片中 Mark 出要修改的区域，然后通过 prompt 引导大模型修改指定位置，或者生成指定轮廓的图。这样可以严格的控制生成出来对象的外形，位置，大小等 （尽量确保输入输出都是标准尺寸，反之隐含的偏移，导致 mark 不准）
画布尺寸注意事项
使用 AI 生图时，输入输出尺寸是一个非常重要的参数！
推荐尺寸
下面这些尺寸可以作为调用 nano banana 时优先采用的标准目标尺寸。调用生图工具时，尽量确保输入输出图片尺寸一致且符合下述尺寸。。
| 比例 | 1k | 2k |
|---|---|---|
1:1 | 1024 x 1024 | 2048 x 2048 |
3:4 | 896 x 1200 | 1792 x 2400 |
4:3 | 1200 x 896 | 2400 x 1792 |
2:3 | 848 x 1264 | 1696 x 2528 |
3:2 | 1264 x 848 | 2528 x 1696 |
9:16 | 768 x 1376 | 1536 x 2752 |
16:9 | 1376 x 768 | 2752 x 1536 |
1:4 | 512 x 2064 | 1024 x 4128 |
4:1 | 2064 x 512 | 4128 x 1024 |
1:8 | 352 x 2928 | 704 x 5856 |
8:1 | 2928 x 352 | 5856 x 704 |
9:21 | 336 x 792 | 672 x 1584 |
21:9 | 792 x 336 | 1584 x 672 |
最佳实践
- 除非 API 的官方说明明确写明“支持任意尺寸输入，并且不会引入隐含缩放/裁剪问题”，否则最佳实践是先把输入图片整理为模型的标准目标尺寸之一。
- 如果任务是局部修改，而不是整图重绘，那么“输入尺寸 = 输出尺寸”几乎应视为默认前提，且都是 Nano banana 的标准尺寸
- 如果原图不是标准尺寸，先决定是 padding，还是 Crop；不要把这个决定留给模型隐式处理。
- 如果后续还要继续多轮编辑，第一轮就应把画布尺寸固定下来，后面每一轮都保持一致，这样最容易维持对位关系和像素稳定性。
- Sprite 生成：如果使用 meowart api 的 pixel_gen，那么生成的 sprite 默认都是白色背景，或者透明背景。如果是通用生成，则最好自己在 prompt 里约束 sprite 背景色为白色。
像素风格注意事项
为什么像素图更敏感
- 像素图本质上依赖严格的像素网格，普通图片即使发生轻微缩放很多时候肉眼还能接受，但像素图一旦被错误缩放，边缘、色块和像素颗粒都会被破坏。
- 大模型在做隐含缩放时，采用的通常是双线性采样一类的连续插值（兼容主流的高清图），但对像素图会明显伤害清晰的像素边界。
- 像素图如果必须缩放，原则上应使用邻近采样，而不是双线性或其他平滑插值。
- 因此对于像素资产，最稳妥的做法是先把输入整理到目标尺寸，再要求输出保持同尺寸，确保不要发生缩放。
像素风格的最佳实践
- 像素风格图片尽量不要做拉伸，只做整数倍且等比例 resize，且必须使用邻近采样。
- 对像素风格的 sprite，例如角色、物品、icon 通常都是较小尺寸的
32x32、64x64、128x128这类2^n的方形尺寸, 因此1K和1024 x 1024是Sprite 生成的最优解。 - 如果是基于参考图生成，最佳做法是先把参考图 padding 到合适的
2^n方形，再用邻近采样等比例放大到1024 x 1024，送入 nano banana 生成，并继续输出同样的1024 x 1024（2K则是 2048）。 生成完成后，再用邻近采样等比例缩回目标 sprite 尺寸。这样很多情况下即使不依赖完美像素算法，也能得到严格对齐、边界干净的“完美像素”结果。 - 同时，因为像素块天然是
1:1的方形，在1:1画布里也更容易保持较高的像素块质量。 - 如果是背景图生成等场景，最好一次性生成目标尺寸附近的图，之后稍微 crop 即可，减少缩放导致的像素挤压效应。
MeowArt API 相关文档
meowart_api.md：面向日常使用的快速说明，重点整理了最常用的命令入口、鉴权方式和典型调用示例。适合在已经明确需求后，直接查“该用哪个命令、参数怎么写”。meowart_api.py：实际调用 MeowArt API 的脚本封装，包含各个子命令的参数定义、请求发送、轮询、下载和输出目录处理逻辑。遇到需要更细粒度控制参数、确认底层行为，或者扩展新调用方式时，应直接阅读这个脚本。
输出目录规则
- 用户要求一批资产或统一位置时，先创建本次任务专用资产根目录，例如
./.meowart-test/<task_slug>/或项目约定的assets/generated/<task_slug>/；之后所有生成、后处理、动画命令都显式传这个根目录下的子目录作为--output-dir。 --work-dir是命令日志/元数据目录；--output-dir才是图片、动画、sprite 等资产目录。只有meta.json的目录通常不是最终资产目录。credits-balance、pixel-gen-template-info这类查询命令通常只生成 JSON；gemini-generate-content和各类*-run命令才会下载资源文件。- 任务完成后，用图片尺寸/帧数做一次快速校验，确认关键文件实际落在用户指定的统一目录下。
实战指南
- 多做对齐：每次生图图片之前，尽量先确认好需求。生成之后也让用户确认一下品质（或者你自己确认），最好不要一上来就大规模生成，而是先选一两个模板，
- 文档编写：随着开发，交流，生成的过程，最好持续的更新文档，例如写到项目根目录下的
AGENTS.md里，在里面开一个章节，记录美术相关的只是，例如美术风格，资产要求（如画布尺寸，sprite 尺寸等），资产分布，生成过程的记录等。这可以让提高整体美术开发的效率和一致性。
场景生成
- 游戏背景图或者场景图，通常优先使用通用的
gemini-generate-content。 - 固定尺寸背景图：直接走通用生成模式，在描述里明确风格、主体和镜头关系。例如“像素风格的夜空和烟花”。这里最重要的是先选一个接近最终画布的尺寸比例，例如
16:9，这样后续通常只需要轻微 crop，不必再做大幅缩放。 - 如果用户明确要
2K、16:9等尺寸，不要只在 prompt 里写尺寸；同时传generationConfig.imageConfig，例如：python3 skills/game-assets/meowart_api.py gemini-generate-content \ --text "Generate a 2K 16:9 game background..." \ --generation-config '{"responseModalities":["TEXT","IMAGE"],"imageConfig":{"aspectRatio":"16:9","imageSize":"2K"}}' \ --output-dir./outputs/background_2k_16x9生成后必须检查实际尺寸；16:9 2K期望是2752 x 1536。 - 无限循环背景图：先生成一张普通背景图(最好在 prompt 中提前说明这是横向游戏还是纵向游戏的背景,否则图片的横纵比或者内容太差，可能无法改造为自我循环)。然后再调用
self-loop-run，把它转成横向或纵向可无缝循环的背景，用于卷轴场景或重复平铺纹理。需要四向连续时传--mode full。
角色生成
- 人物、怪物、道具、Icon 这类资源，通常先通过
pixel-gen-template-info查看可用模板。选择模板生成之前如果条件允许，可选择几个备选项，将preview_image_url的图片下载下来，并在对话窗口里直接展示给用户，进行一次风格的对齐。 - 不同模板的主要差异在于美术风格、单张图片尺寸，以及一次可批量生成的数量。原则上模板本身都是通用的，都可以通过 prompt 生成任意内容；但选一个更合适的模板，会明显提高结果确定性，也更容易维持整个项目的美术统一。
- 模板选择建议：
- 物品、Icon、小动物：优先考虑 food、object 模板（这两个模板最好看也最通用），单次通常可以生成 8 个 64x64 像素对象。 - 人物、主角、怪物角色：优先考虑 pixel_char 模板，单次通常可以生成 2 个 128x128 对象。 - 具体模板名称和批量数量仍以 pixel-gen-template-info 的返回为准；如果服务端模板列表发生变化，先按返回信息调整。
- 正式生成时使用
pixel-gen-run，模板通常都已经自带了一套风格，因此无需再大量的笔墨去描述风格，只用简单描述一下外观，批量生成多个内容的时候可以说清楚每一个物体的类型（例如折耳猫，波斯猫……）。 - 对于批量模板，
requirement更接近“这一批要生成什么”，而不是最终直接发给模型的完整 prompt。系统会结合模板自己的target_count再包装成真正的生成提示词。例如cat_2默认会生成8个 sprite，因此写猫咪也会被解释成“生成 8 个猫咪”；如果想让这一批结果更有区分度，应该直接写变体列表，例如“三花、橘猫、奶牛猫、暹罗、英短、美短、狸花、纯白猫”。 - 批量生成时，既可以在
requirement里分别描述多个对象的外观，也可以用一句话简单描述整体需求，让服务端的 Agent 自己细化。尽量一次性生成模板支持的最大数量，因为同一模板下价格和质量通常没有区别，多生成一些更方便挑选。 - 对于 pixel-gen 模板，像“白色背景”“像素风格”这类模板本身已经隐含的约束，通常不需要在
requirement里重复强调，除非这次任务确实要覆盖模板默认行为。 - 如果是横版过关游戏，或者类吸血鬼幸存者游戏，优先考虑带
direction的模板，用left或right这类侧面视角会更贴合游戏表现；如果还是用普通模板，也要在 prompt 里明确写清楚角色视角。 - 当前这套模板主要面向 Pixel 风格 Sprite；如果要做高清二次元、厚涂、插画风角色，只能先用通用的
gemini-generate-content生成，再自行抠图或后处理。 - 如果用户明确“不使用 template”但要像素角色，走通用生图生成白底单角色，再按顺序执行：
pixelate-run收敛成像素图，remove-background-run --method pixel去白底，最后校验 PNG 是RGBA且尺寸符合接入需求。默认不要手动传--pixel-size，优先让服务端自动估计；只有明确目标尺寸或已验证参数时才指定，例如同一输入下--pixel-size 16可能比--pixel-size 8更接近128x128sprite。 - 人物主角、Boss、立绘感更强的角色，通常更适合选单次只生成
1到2个的大尺寸模板。批量敌人、批量道具、Icon 等，则更适合一次生成8个左右的模板，提高效率并确保同批资源风格一致。 - 不同模板生成出来的 sprite 尺寸可能不同，接入游戏代码时要注意统一 resize。像素图只能使用邻近采样，并尽量保持整数倍缩放，例如
2x、3x；不要使用0.85x、1.2x这类非整数缩放，否则会破坏像素质感。
动画生成
- 角色或物体的攻击、死亡、移动、跳跃、弹跳等动作，通常使用
animate-run。 - 输出通常会包含
gif、webp、png三种格式；其中png一般已经去掉背景，可以直接作为 sprite sheet 接入游戏。 - 最佳顺序通常不是一开始就做动画，而是先把静态 Sprite 做出来，并在游戏里验证尺寸、透视、美术风格、碰撞盒、游戏性都没有问题后，再进入动画阶段。
- 这样做的原因是
animate-run相对更慢、费用也更高，更适合作为资产定稿前的最后一步，而不是前期反复试错的主流程。 - 动画接口偶尔会返回临时
502或轮询异常：如果提交阶段已经打印api_job_id，用animate-poll --api-job-id <id>复查并下载；如果提交阶段没有拿到 job id，直接重试animate-run。
UI 生成
- 目前工具里没有真正端到端的 UI 生成接口，但可以通过通用生图和其他 API 组合出一套可用流程。
- 第一步：先截取真实游戏画面。
- 第二步：使用
gemini-generate-content做通用生成，例如让模型“在这个游戏画面左上角添加一个角色状态栏 UI，包含血量，经验，头像等，并保持整体美术风格一致”。 - 第三步：拿到视觉稿后，一般有两条路线。
- 编程复刻：根据视觉稿，用代码来复刻 UI。这条路线更可控，生成之前可以先给用户看一下 UI是否符合要求。。 - 提取 UI Sprite：继续使用通用生图，把 prompt 改成“将画面左上角人物角色状态栏的 UI 提取到白色背景上，删除其他所有背景、人物和 UI，只保留角色状态栏，并保持白色背景”。得到结果后，再调用 remove-background-run 去除白底；最后结合 crop 或手工微调尺寸，就可以得到可直接用于游戏中的 UI Sprite。