blockbench-gpt-image-textures

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GPT Image 2.5 Textures for Blockbench

Blockbench 的 GPT Image 2.5 纹理

Generate a texture image with GPT Image 2.5 on fal.ai and land it on an existing Blockbench UV layout. The prompt must carry the UV layout: which pixel rectangle of the image belongs to which face. Without it the model paints a picture, not an atlas.

Load blockbench-use first for discovery and verification rules, and blockbench-texturing for UV inspection and cleanup painting.

在 fal.ai 上使用 GPT Image 2.5 生成纹理图像，并将其贴合到现有的 Blockbench UV 布局上。提示词必须包含 UV 布局：图像中的哪个像素矩形对应哪个面。否则，模型绘制出来的是一幅图片，而不是纹理图集。

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

Pick a model

选择模型

Model	fal endpoint	Use for
Flare (default)	`openai/gpt-image-2.5/flare/text-to-image`	Fast drafts, most atlases, transparent backgrounds
Sunburst	`openai/gpt-image-2.5/sunburst/text-to-image`	Final high-resolution atlases with intricate detail; slower

Both accept the same parameters and share

/edit

variants that take reference images. Details, pricing and recipes: references/fal-api.md.

模型	fal endpoint	用途
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。

Workflow

工作流

0. Settle the geometry/detail tradeoff

0. 确定几何体与细节的权衡

For a new model or substantial redesign, resolve the appearance/accuracy, performance, or balanced preference through blockbench-use before committing geometry or generating an atlas. Apply appearance and performance planning: establish the simplified target geometry and shared UV tiles first. An HD image request is not permission to multiply tiny detail cubes.

For braces or railing infills represented by panels, describe the repeated pattern and transparent holes inside each measured UV region, not just transparency outside the atlas islands. For fasteners represented on existing faces, include their albedo marks in those regions and use the PBR workflow for supported normal/height/MER detail. Verify channel data separately; a color atlas is not a PBR map. Confirm Bedrock material bindings when cutouts or multiple materials are intended for a custom block.

对于新模型或大幅改造，先通过 blockbench-use 确定偏好采用外观/准确度、性能还是均衡方案，再提交几何体或生成图集。应用外观与性能规划：先确定简化的目标几何体和共享 UV 瓦片。请求 HD 图像并不代表可以大量增加微小细节方块。

对于以面板形式表现的支架或栏杆填充件，应描述重复图案以及每个已测量 UV 区域内部的透明孔洞，而不只是描述图集各区域之外的透明部分。对于绘制在现有面上的紧固件，应在这些区域中加入其 albedo 标记，并使用 PBR 工作流生成受支持的 normal/height/MER 细节。通道数据需要单独验证；彩色图集不是 PBR 贴图。如果自定义方块需要镂空或多种材质，请确认 Bedrock 材质绑定。

1. Establish the UV layout first

1. 首先建立 UV 布局

The atlas layout must exist in Blockbench before prompting. Run

get_capabilities: include_tools=true

, then

list_textures

. If no texture or UVs exist, generate a native texture template as described in the texturing skill, then continue. Do not invent a layout in the prompt that the model does not have.

Audit that layout using UV scale and distortion guidance before generation. Compare surface dimensions with sampled image pixels along both face directions, using the effective frame and logical UV sizes. Correct unintended stretching and inconsistent material scale first; an image generator cannot repair a distorted mapping just by painting inside its rectangles. Reusing the same complete swatch is appropriate only for compatible face dimensions or deliberate exceptions.

Collect the layout:

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

Save the raw results into one JSON file:

json

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

图集布局必须先在 Blockbench 中存在，然后才能编写提示词。运行

get_capabilities: include_tools=true

，然后运行

list_textures

。如果不存在纹理或 UV，请按照纹理 skill 中的说明生成原生纹理模板，然后继续操作。不要在提示词中虚构模型实际上并不存在的布局。

生成前，使用 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 文件中：

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. Compute the canvas and regions

2. 计算画布和区域

fal rejects images under 655,360 pixels, so a 64x64 atlas cannot be generated at native size. Generate an integer upscale and downsample afterwards. The script picks the scale and converts every face rectangle into generated-image pixels:

bash

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

Output includes

image_size

(pass to fal unchanged),

canvas.texel_scale

, one region per face with

px

and

texels

rectangles, and

shared_regions

for faces that reuse the same pixels. An exit code of 2 means the atlas aspect exceeds 3:1; generate a padded canvas and crop with

--crop

in step 5, or split the atlas.

canvas.texel_scale

describes the generation upscale, not material density on the model. Collect surface dimensions separately from the geometry; the region list alone cannot establish pixels per model unit or detect local mesh distortion.

fal 会拒绝像素总数低于 655,360 的图像，因此无法按原生尺寸生成 64x64 图集。应按整数倍放大生成，随后再进行降采样。脚本会选择缩放比例，并将每个面的矩形转换为生成图像中的像素坐标：

bash

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. Write the prompt with the layout inside it

3. 编写包含布局的提示词

Structure the prompt as JSON. The

layout

block is mandatory and comes straight from step 2. Read references/uv-layout-prompting.md for the full template, region-description rules and worked examples. Minimum shape:

json

{
  "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"
  ]
}

Describe what each face shows, not the 3D scene. Name regions by cube and direction, keep the pixel rectangles exactly as computed, and mention rotation or mirroring the script reported.

For detailed materials, describe each region's surface coverage in model units, grain direction, and consistent feature size across related regions. Larger surfaces normally show more repetitions of the same grain or pattern. Preserve individual UV footprints when grouping descriptions by material; do not map one full material rectangle onto every differently sized face. Coordinate these choices with all PBR channels.

将提示词组织为 JSON。

layout

块是必需的，内容应直接来自第 2 步。阅读 references/uv-layout-prompting.md，了解完整模板、区域描述规则和示例。最低结构如下：

json

{
  "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. Generate

4. 生成

bash

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

Use

--width/--height

from

layout.json

image_size

--background transparent

yields real alpha on Flare; verify alpha on Sunburst output before relying on it. Start with

medium

quality and

--num 2

to pick a candidate;

high

xhigh

only for finals.

--dry-run

prints the request body for review. Download happens inside the script; fal URLs expire.

bash

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 上生成实际的 alpha 通道；使用 Sunburst 输出前需验证 alpha。先使用

medium

质量和

--num 2

生成候选图；仅在最终稿中使用

high

或

xhigh

。

--dry-run

会打印请求体供审核。下载过程在脚本内部完成；fal URL 会过期。

5. Downscale to the atlas

5. 降采样到图集尺寸

Skip this step when

texel_scale

is 1. Otherwise sample the centre of each texel block with nearest-neighbour and snap alpha for pixel art:

bash

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

Use

--sample average

for painterly high-resolution atlases, and

--crop X Y W H

to cut a padded canvas back to the atlas aspect first.

当

texel_scale

为 1 时跳过此步骤。否则，使用最近邻采样选取每个纹素块中心点的颜色，并为像素艺术将 alpha 按阈值吸附：

bash

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. Import, apply and verify in Blockbench

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

In formats with

per_texture_uv_size

, pass

uv_width

uv_height

create_texture

matching the original atlas

uv_size

. Check the rendered model for region drift, seam bleeding, mirrored content, and inconsistent grain or relief scale. Use a temporary checker to distinguish mapping distortion from inconsistent detail painted into the atlas; inspect long/short faces and sides/ends at close and intended viewing distances.

When generated boundaries drift, repaint or extend the material to fit the planned UV footprint. Avoid independently fitting each face's UV rectangle to the generated content bounds: that can alter both aspect ratio and density. If UV edits are necessary, preserve proportions and intended density, update corresponding PBR regions, and repeat the scale checks. Fix small image errors with the texturing skill's paint tools. For larger errors, iterate through the

/edit

endpoint with the previous output URL and a prompt naming only the regions to change.

Once the color atlas is final, derive its normal, height and MER maps with albedo to normal rather than generating PBR channels with the image model; run it on the downscaled atlas so the maps share the texel grid.

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

。检查渲染后的模型，排查区域漂移、接缝渗色、内容镜像，以及纹理颗粒或浮雕比例不一致的情况。使用临时棋盘格纹理来区分映射变形与图集中绘制细节不一致的问题；在近距离和预期观看距离下检查长面/短面以及侧面/端面。

当生成内容的边界发生漂移时，应重新绘制或扩展材质，使其适配规划的 UV 覆盖范围。不要让每个面的 UV 矩形分别适配生成内容的边界：这可能同时改变宽高比和密度。如果必须编辑 UV，应保持比例和预期密度，更新相应的 PBR 区域，并重复比例检查。使用纹理 skill 的绘制工具修复小型图像错误。对于较大错误，可通过

/edit

endpoint 反复迭代，传入上一次输出的 URL，并使用只指定需要更改区域的提示词。

彩色图集定稿后，使用 albedo to normal 从 albedo 派生 normal、height 和 MER 贴图，而不是使用图像模型生成 PBR 通道；应在降采样后的图集上运行，使各贴图共享同一纹素网格。

What to expect

预期结果

The model treats pixel rectangles as guidance, not a contract. Expect 1 to 3 texel drift at region borders and occasional content spilling into transparent gutters; the downscale and cleanup pass absorb most of it.
Fewer, larger regions work better than many tiny ones. For atlases with more than about 20 regions, group by body part in the prompt and describe shared regions once.
Pixel-art phrasing ("each texel a solid 16x16 px block") keeps blocks aligned to the texel grid. Without it the model anti-aliases and the downscale muddies edges.
A rendered UV template or checker fed through
```
/edit
```
as
```
image_urls
```
anchors the layout far more reliably than text alone. Use
```
capture_screenshot
```
or the native template texture, upload it, and prompt "paint this texture sheet" with the same
```
layout
```
block.
Long text, logos and readable labels belong in a separate pass; they compete with the layout rules.
Every output is a full RGB(A) image; nothing prevents the model from painting outside regions. Verify against
```
get_cube_uv
```
rectangles, not against the prompt.

模型将像素矩形视为指导，而不是硬性约束。预期区域边界会出现 1 到 3 个纹素的漂移，内容偶尔也会溢出到透明的间隔区域；降采样和清理流程可以消除大部分偏差。
少量的大区域比大量的小区域效果更好。对于区域超过约 20 个的图集，在提示词中按身体部位分组，并只描述一次共享区域。
像素艺术表述（"each texel a solid 16x16 px block"）能够使像素块与纹素网格保持对齐。如果没有这一表述，模型会进行抗锯齿，降采样后边缘会变得模糊。
将渲染后的 UV 模板或棋盘格纹理通过
```
/edit
```
作为
```
image_urls
```
输入，比仅靠文本更能可靠地固定布局。使用
```
capture_screenshot
```
或原生模板纹理进行上传，并使用相同的
```
layout
```
块提示“paint this texture sheet”。
长文本、Logo 和可读标签应放在单独的流程中处理；它们会与布局规则争夺模型的注意力。
每个输出都是完整的 RGB(A) 图像；没有任何机制能阻止模型绘制到指定区域之外。请根据
```
get_cube_uv
```
矩形进行验证，而不是仅依据提示词。

Resources

资源

references/fal-api.md: endpoints, parameters, sizes, pricing, transparency, curl/Node/Python recipes, edit endpoint.
references/uv-layout-prompting.md: prompt template, how to describe box-UV nets, per-face rectangles and mesh islands, worked examples for Bedrock entity, Java block and Generic Model targets.
```
scripts/uv_layout_prompt.mjs
```
: inspection JSON to canvas size and pixel regions.
```
scripts/fal_gpt_image.mjs
```
: call Flare or Sunburst (text-to-image or edit), save results.
```
scripts/resize_to_atlas.py
```
: nearest-neighbour or box downscale to atlas size, optional crop and alpha snap (needs Pillow).

references/fal-api.md：端点、参数、尺寸、定价、透明度、curl/Node/Python 用法以及编辑 endpoint。
references/uv-layout-prompting.md：提示词模板、如何描述 box-UV 网格、逐面矩形和网格岛，以及面向 Bedrock 实体、Java 方块和 Generic Model 目标的示例。
```
scripts/uv_layout_prompt.mjs
```
：将检查 JSON 转换为画布尺寸和像素区域。
```
scripts/fal_gpt_image.mjs
```
：调用 Flare 或 Sunburst（text-to-image 或 edit）并保存结果。
```
scripts/resize_to_atlas.py
```
：使用最近邻或 box 方法将图像降采样到图集尺寸，并支持可选的裁剪和 alpha 吸附（需要 Pillow）。