blockbench-gpt-image-textures

GPT Image 2.5 用于 Blockbench 纹理

在 fal.ai 上使用 GPT Image 2.5 生成纹理图像，并将其映射到现有的 Blockbench UV 布局上。提示词必须包含 UV 布局：图像中的哪些像素矩形对应哪个面。没有这些信息，模型只会画一幅图，而不是图集。

请先加载 blockbench-use，了解发现和验证规则；再加载 blockbench-texturing，进行 UV 检查和清理绘制。

选择模型

模型	fal 端点	适用场景
Flare（默认）	openai/gpt-image-2.5/flare/text-to-image	快速草稿、大多数图集、透明背景
Sunburst	openai/gpt-image-2.5/sunburst/text-to-image	最终高分辨率图集和复杂细节；速度较慢

两者接受相同的参数，并共享可接收参考图像的 /edit 变体。详情、定价和配方：请参阅 references/fal-api.md。

工作流

0. 确定几何与细节之间的取舍

对于新模型或大幅重新设计，请先通过 blockbench-use 确定外观与精度、性能或平衡方面的偏好，再确定几何结构或生成图集。应用外观与性能规划：先确定简化后的目标几何结构和共享 UV 瓷砖。请求 HD 图像并不意味着可以增加大量细小细节立方体。

对于用面板表示的支撑杆或栏杆填充部分，请在每个经过测量的 UV 区域内描述重复图案和透明孔洞，而不只是描述图集岛之外的透明区域。对于绘制在现有面上的紧固件，请在对应区域中包含其反照率标记，并使用 PBR 工作流添加受支持的法线／高度／MER 细节。请分别验证各通道的数据；颜色图集不是 PBR 贴图。如果自定义方块需要使用镂空或多种材质，请确认 Bedrock 材质绑定。

1. 先确定 UV 布局

提示词编写前，Blockbench 中必须已有图集布局。运行 get_capabilities: include_tools=true，然后运行 list_textures。如果没有纹理或 UV，请按照纹理技能中的说明生成原生纹理模板，然后继续。不要在提示词中编造模型并不存在的布局。

生成前，请根据 UV 比例和失真指南审核布局。使用有效帧和逻辑 UV 尺寸，对比表面尺寸与沿各面两个方向采样的图像像素数。先修正意外拉伸和材质比例不一致的问题；图像生成器无法仅靠在矩形内绘制来修复失真的贴图。只有面尺寸兼容或作为有意例外时，才适合复用相同的完整色样。

收集布局：

list_textures                              # frame_size and uv_size of the target atlas
get_cube_uv: id="<cube uuid>"              # one call per textured cube
get_mesh_info: mesh_id="<uuid>", include_uv=true   # meshes, if any

将原始结果保存到一个 JSON 文件中：

{ "textures": [ ...list_textures... ], "cubes": [ ...get_cube_uv results... ],
  "meshes": [ { "name": "cloth", "faces": [ { "key": "f1", "uv": [[40,40],[56,40],[56,52],[40,52]] } ] } ] }

2. 计算画布和区域

fal 会拒绝小于 655,360 像素的图像，因此无法按原生尺寸生成 64x64 图集。请按整数倍放大生成，然后再缩小。脚本会选取缩放倍数，并将每个面的矩形转换为生成图像中的像素坐标：

node scripts/uv_layout_prompt.mjs inspection.json --texture <atlas name|uuid> > layout.json
node scripts/uv_layout_prompt.mjs inspection.json --format text   # human-readable check

输出包含 image_size（原样传给 fal）、canvas.texel_scale、每个面的一个区域（含 px 和 texels 矩形），以及用于表示复用相同像素的面的 shared_regions。退出代码为 2 表示图集长宽比超过 3:1；请生成带留白的画布，并在步骤 5 中使用 --crop 裁剪，或拆分图集。

canvas.texel_scale 表示生成时的放大倍数，而非模型上的材质密度。请从几何结构中单独收集表面尺寸；仅凭区域列表无法确定每个模型单位对应的像素数，也无法检测局部网格失真。

3. 在提示词中加入布局

将提示词构建为 JSON。必须包含 layout 块，并直接使用第 2 步的内容。完整模板、区域描述规则和示例请参阅 references/uv-layout-prompting.md。最简结构如下：

{
  "type": "UV texture atlas for a low-poly 3D game model, flat orthographic texture sheet, not a 3D render",
  "subject": "brown alpaca, cartoon Minecraft style",
  "style": "crisp pixel art, each texel a solid 16x16 px block, no anti-aliasing, 12-color palette, flat unlit colors",
  "canvas": { "width": 1024, "height": 1024, "texel_scale": 16, "represents": "64x64 texel atlas" },
  "background": "fully transparent outside the listed regions",
  "regions": [
    { "name": "head/north (face)", "px": [128, 128, 256, 256], "paint": "front of the head: two dark eyes, muzzle, no outline" },
    { "name": "head/up",   "px": [128, 0, 256, 128], "paint": "top of head fur, seam-continuous with head/north" }
  ],
  "rules": [
    "paint every region edge to edge; leave everything else transparent",
    "no labels, grid lines, borders, drop shadows or text anywhere",
    "adjacent faces of one cube must continue seamlessly across their shared edge",
    "regions listed as shared receive identical content"
  ]
}

描述每个面上显示的内容，而不是 3D 场景。按立方体和方向命名区域，保持像素矩形与计算结果完全一致，并注明脚本报告的旋转或镜像情况。

对于精细材质，描述每个区域在模型单位下的表面覆盖范围、纹理方向，以及相关区域之间一致的特征尺寸。较大的表面通常会显示更多重复的相同纹理或图案。按材质分组描述时，应保留各自独立的 UV 占用范围；不要将一个完整的材质矩形映射到尺寸不同的每个面上。这些选择应与所有 PBR 通道协调一致。

4. 生成

FAL_KEY=... node scripts/fal_gpt_image.mjs --prompt-file prompt.json --model flare \
  --width 1024 --height 1024 --background transparent --quality medium --num 2 --out ./output --label alpaca

使用 layout.json 中 image_size 的 --width/--height。--background transparent 会在 Flare 上生成真实透明度；依赖 Sunburst 输出前，请先验证透明度。从 medium 质量和 --num 2 开始，以挑选候选结果；只有最终版本才使用 high 或 xhigh。--dry-run 会打印请求正文以供检查。脚本会在内部下载文件；fal URL 会过期。

5. 缩小到图集尺寸

当 texel_scale 为 1 时跳过此步骤。否则，使用最近邻采样每个纹素块的中心，并为像素艺术对 Alpha 进行取整：

python scripts/resize_to_atlas.py output/alpaca_<ts>.png output/alpaca_64.png --width 64 --height 64 --alpha-threshold 128

对于绘画风格的高分辨率图集，使用 --sample average；若要先将带边距的画布裁回图集宽高比，请使用 --crop X Y W H。

6. 在 Blockbench 中导入、应用并验证

create_texture: name="alpaca", data="<absolute path to alpaca_64.png>"
apply_texture: id="<group or element>", texture="alpaca", applyTo="all"
get_texture: texture="alpaca"
capture_screenshot

对于具有 per_texture_uv_size 的格式，传入与原始图集 uv_size 相匹配的 uv_width/uv_height，以供 create_texture 使用。检查渲染后的模型是否存在区域偏移、接缝渗色、内容镜像，以及纹理或凹凸比例不一致的问题。使用临时检查器区分映射失真与绘制到图集中的细节不一致；在近距离和预期观看距离下检查长面／短面以及侧面／端面。

如果生成的边界发生偏移，请重新绘制或延伸材质，使其符合规划的 UV 占用范围。避免将每个面的 UV 矩形单独调整到生成内容的边界：这可能会改变宽高比和密度。如果必须编辑 UV，请保留比例和预期密度，更新对应的 PBR 区域，并重复比例检查。使用纹理技能的绘制工具修复小的图像错误。对于较大的错误，通过 /edit 端点进行迭代，使用上一次输出的 URL，并在提示词中仅指出需要修改的区域。

颜色图集定稿后，使用 albedo to normal 从图集生成法线、高度和 MER 贴图，而不是使用图像模型生成 PBR 通道；请在缩小后的图集上运行，以确保贴图共用同一纹素网格。

预期效果

• 模型将像素矩形视为参考，而非硬性约束。区域边界可能偏移 1 到 3 个纹素，内容偶尔会溢出到透明边距；缩小和清理步骤会消除大部分偏差。
• 使用较少、较大的区域，效果优于使用许多微小区域。对于区域超过约 20 个的图集，请在提示词中按身体部位分组，并对共用区域统一描述。
• 使用像素艺术措辞（“每个纹素都是一个纯色的 16x16 px 方块”）可以让方块与纹素网格对齐。否则，模型会进行抗锯齿处理，缩小后边缘会变得模糊。
• 通过 /edit 将渲染好的 UV 模板或棋盘格作为 image_urls 输入，比单靠文字更可靠地固定布局。使用 capture_screenshot 或原生模板纹理，上传后使用相同的 layout 区块，并提示“绘制这张纹理表”。
• 长文本、Logo 和可读标签应单独处理；它们会与布局规则相互干扰。
• 每个输出都是完整的 RGB(A) 图像；模型可以在区域之外绘制。请对照 get_cube_uv 矩形进行验证，而不是对照提示词。

资源

• references/fal-api.md：端点、参数、尺寸、定价、透明度、curl/Node/Python 示例和编辑端点。
• references/uv-layout-prompting.md：提示词模板、如何描述盒式 UV 展开图、逐面的矩形和网格岛屿，以及适用于 Bedrock 实体、Java 方块和 Generic Model 目标的示例。
• scripts/uv_layout_prompt.mjs：将检查 JSON 转换为画布尺寸和像素区域。
• scripts/fal_gpt_image.mjs：调用 Flare 或 Sunburst（文本生成图像或编辑），并保存结果。
• scripts/resize_to_atlas.py：使用最近邻或盒式采样缩小到图集尺寸，可选裁剪和 Alpha 吸附（需要 Pillow）。