layer-typography

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Layer Typography

Layer 排版

Overview

概述

Image models misspell words and cannot use a font file. When copy must read exactly or be set in a brand typeface, do not generate it: set it with

render_text

, then place it on the art with

compose_image

. The art and the type stay separate files, so a copy change is a re-render, not a regeneration, and the same art can carry every language (

layer-localization

Both tools are named directly rather than discovered because they are Layer's own deterministic file operations, not models: no model runs, no Creative Units are spent, and no estimate is needed for them. The art underneath is still a billed generation and goes through the usual estimate gate in the

layer

skill.

Not all lettering belongs here.

render_text

sets flat, single-colour type. Lettering that must look drawn into the scene (a carved sign, a neon tube, a painted title with texture) is a generation, and

layer-image

covers prompting for it.

If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add layerai/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

图像模型会拼错单词，也无法使用字体文件。当文案必须准确呈现或采用品牌字体时，不要直接生成它：应先使用

render_text

设置文字，再通过

compose_image

将其放置到画面上。画面与文字会保存在两个独立文件中，因此修改文案时只需重新渲染，而不必重新生成画面；同一份画面还可以承载所有语言（

layer-localization

）。

这两个工具之所以需要直接指定，而不是通过发现机制获取，是因为它们属于 Layer 自带的确定性文件操作，而非模型：运行过程中不会调用模型，不会消耗 Creative Units，也不需要进行预估。底层画面仍属于计费生成任务，需要经过

layer

skill 中常规的预估确认流程。

并非所有文字设计都适合在这里处理。

render_text

只能设置扁平的单色文字。如果文字需要呈现为融入场景的手绘效果（例如雕刻招牌、霓虹灯管或带纹理的喷绘标题），则应通过生成方式完成，并由

layer-image

负责相关提示词。

如果此处提到的某个同级 skill 不在可用 skill 列表中，请要求用户安装（

npx skills add layerai/skills --skill <name>

）；在无人值守模式下，则根据 tool schema 继续执行，并指出缺失项。

Quick reference

快速参考

Need	Route
Exact copy, brand font, editable later	`render_text` , then `compose_image` over the art
Lettering that is part of the illustration	A generation ( `layer-image` )
Change words already baked into an image	`list_base_models` with `filter.use_case: "edit_text"`
Brand font on the user's disk	`request_file_upload_url` , then pass the `file_id` as `font_file_id`
Brand font at a public URL	`upload_file`
No font file	`font_family` : a standard font or a Google Fonts family name

需求	处理方式
精确文案、品牌字体、后续可编辑	`render_text` ，然后通过 `compose_image` 叠加到画面上
作为插画一部分的文字	使用生成方式（ `layer-image` ）
修改已经嵌入图片中的文字	使用 `list_base_models` ，并设置 `filter.use_case: "edit_text"`
用户本地磁盘上的品牌字体	`request_file_upload_url` ，然后将 `file_id` 作为 `font_file_id` 传入
公共 URL 上的品牌字体	`upload_file`
没有字体文件	`font_family` ：指定标准字体或 Google Fonts 字体家族名称

Setting the type

设置文字

Upload the brand font before anything else. A

font_file_id

takes precedence over

font_family

, and

font_weight

(100 to 900 in steps of 100, 400 regular, 700 bold) picks the face inside that file, with

italic

for the italic face. Without a file,

font_family

falls back to a named family, which is a different typeface from the brand's even when it looks close. Tell the user when that happens.

Size the canvas (

width

height

, at most 4096 each) to roughly the box the text will fill in the final image, so it is barely scaled when placed. Text set small and scaled up goes soft; text set huge and scaled down loses its weight.

Text that does not fit is refused with the size it needs. Read that size and decide: a bigger box, a smaller

font_size

, or shorter copy. Do not shrink the font silently until it fits, because a title that fits by being tiny has failed.

Two alignments do different jobs.

horizontal_alignment

and

vertical_alignment

place the block on the canvas;

text_align

aligns the lines of a multi-line block with each other. A newline starts a new line and long lines wrap at spaces.

line_height

only loosens spacing.

The canvas is transparent unless

background_color

is set.

#RRGGBBAA

gives a translucent plate behind the words, which is the simplest contrast fix over busy art.

Flat single-colour type has no outline or shadow. For a drop shadow, render the same text twice, once in a dark colour and once in the face colour, and stack them in

compose_image

with the dark copy offset a few pixels down and right.

在任何操作之前，先上传品牌字体。

font_file_id

的优先级高于

font_family

；

font_weight

（取值范围为 100 至 900，步长为 100，其中 400 为常规、700 为粗体）用于选择字体文件中的具体字重，使用

italic

可选择斜体字形。如果没有字体文件，

font_family

会回退到指定的字体家族；即使外观接近，它也与品牌字体不同。此时应告知用户。

将画布尺寸（

width

、

height

，每项最大为 4096）设置得大致接近文字在最终图片中所占的区域，以便放置时几乎不需要缩放。小尺寸文字放大后会变模糊；超大尺寸文字缩小后会失去字重。

如果文字无法容纳，系统会拒绝渲染并返回所需的尺寸。读取该尺寸后，再决定采用更大的画布、更小的

font_size

，或缩短文案。不要在系统拒绝渲染后悄悄缩小字体，因为一个通过缩得极小才勉强容纳的标题并不是合格的结果。

两种对齐方式承担不同作用。

horizontal_alignment

和

vertical_alignment

用于在画布中定位整个文字块；

text_align

用于让多行文字块中的各行彼此对齐。换行符会开始新的一行，较长的行会在空格处自动换行。

line_height

仅用于调整行间距。

除非设置了

background_color

，否则画布是透明的。

#RRGGBBAA

可在文字后面提供半透明底板，这是解决复杂画面上文字对比度问题最简单的方法。

扁平单色文字不支持描边或阴影。如需投影，可将同一段文字渲染两次：一次使用深色，一次使用字面色，然后在

compose_image

中叠放，将深色副本向右下方偏移几个像素。

Placing it

放置文字

compose_image

stacks up to 16 layers into one flat PNG, bottom first. The canvas defaults to the first layer's image size, so put the art first and the canvas matches it.

Anchors are pixel offsets from the canvas edges. Set
```
left
```
and
```
right
```
together and the box spans between them. To pin text to a corner or centre it without knowing its size, anchor all four sides at the margin and set
```
horizontal_alignment
```
and
```
vertical_alignment
```
.
```
width
```
and
```
height
```
sit on the layer beside
```
anchors
```
, never inside it.
resize_strategy
:
```
fit_and_pad
```
for text and logos, so they scale into the box without distortion.
```
fit_and_crop
```
is for full-bleed backgrounds. Never
```
stretch
```
type.
Rotation turns a layer 90, 180 or 270 degrees: vertical spine text, or a card's index set upside down in the opposite corner.

compose_image

最多可将 16 个图层叠加为一个扁平 PNG，图层顺序从底部开始。画布默认采用第一个图层的图片尺寸，因此应先放置画面，使画布与其尺寸一致。

锚点是相对于画布边缘的像素偏移。同时设置
```
left
```
和
```
right
```
后，文字框会横跨两者之间。如果需要将文字固定在某个角落或中央且事先不知道其尺寸，可以将四边都锚定在边距位置，并设置
```
horizontal_alignment
```
和
```
vertical_alignment
```
。
```
width
```
和
```
height
```
是图层上与
```
anchors
```
并列的属性，不能放在
```
anchors
```
内部。
resize_strategy
：文字和 Logo 应使用
```
fit_and_pad
```
，使其在不失真的情况下缩放到框内；
```
fit_and_crop
```
适用于铺满全屏的背景。切勿对文字使用
```
stretch
```
。
旋转可将图层旋转 90、180 或 270 度，例如用于竖排书脊文字，或将卡片角落的序号倒置。

Legibility

可读性

Judge the composite at the size it will be seen, not at full resolution. A store icon label or a mobile button is read at a fraction of the canvas.
Plan the space when the art is generated: ask for a calm, low-detail area where the title will sit. Text over the busiest part of the frame needs a plate, and a plate is a compromise.
Keep a safe margin from every edge. Platforms crop and overlay their own UI, and a CTA against the edge is the first thing lost.
One typeface, with weight and size for hierarchy, reads as designed. Three reads as a ransom note.

应按照素材实际被查看的尺寸评估合成结果，而不是只看全分辨率效果。商店图标标签或移动端按钮通常只会以画布尺寸的一小部分呈现。
在生成画面时就规划好空间：要求模型预留一个安静、低细节的区域，用于放置标题。如果文字覆盖画面中最繁忙的部分，就需要添加底板，而底板本身也是一种妥协。
与每条边缘保持安全间距。平台可能会裁剪画面并叠加自己的 UI，而紧贴边缘的 CTA 通常最先被遮挡或裁掉。
使用一种字体，并通过字重和字号建立层级，会显得有设计感；使用三种字体，则会像拼凑起来的勒索信。

Changing text already in an image

修改图片中已有的文字

When the words are baked into existing art, filter

list_base_models

for

use_case: "edit_text"

, take the first result, and quote the exact replacement string in the prompt. Check the output letter by letter. If it misspells twice, remove the old text to a clean plate instead (an

erase_object

inpainting

model), then letter the plate with

render_text

and

compose_image

当文字已经嵌入现有画面时，使用

filter.use_case: "edit_text"

筛选

list_base_models

，选择第一个结果，并在提示词中用引号标出准确的替换文本。逐字检查输出结果。如果连续两次出现拼写错误，则改为将旧文字清理至干净的底板（使用

erase_object

或

inpainting

模型），再通过

render_text

为底板添加文字，并使用

compose_image

进行合成。

Worked example

实操示例

"Put our title 'Ember Vale' in our brand font on this key art, with 'Pre-register now' under it."

The key art came from an earlier run, so it has a
```
file_id
```
(1920 x 1080). The font is a local
```
.otf
```
:
```
request_file_upload_url
```
, complete the two-step upload, keep the
```
file_id
```
.
```
render_text
```
for the title:
```
font_file_id
```
,
```
font_weight: 700
```
,
```
font_size: 160
```
,
```
color: "#FFF4E0"
```
, a 1200 x 240 canvas. If it is refused, read the size it needs and widen the canvas.
```
render_text
```
the same title in
```
#1A0F08
```
for the shadow.

render_text

the CTA:

font_size: 56

background_color: "#000000B3"

for a translucent plate, a 640 x 112 canvas.

```
compose_image
```
with four layers, bottom first: the key art with no anchors; the shadow anchored
```
top: 124
```
,
```
left: 364
```
, width 1200, height 240; the title at
```
top: 120
```
,
```
left: 360
```
over it; the CTA anchored
```
bottom: 96
```
,
```
left: 640
```
, width 640, height 112, each text layer
```
fit_and_pad
```
.
View the result at the size the user will deliver it. No step here spent Creative Units, so no estimate was needed; say so when reporting.

“把我们的标题 'Ember Vale' 用品牌字体放到这张主视觉上，并在下方添加 '立即预注册'。”

主视觉来自之前的运行，因此已有一个
```
file_id
```
（1920 x 1080）。字体是本地
```
.otf
```
文件：调用
```
request_file_upload_url
```
，完成两步上传，并保留
```
file_id
```
。
使用
```
render_text
```
渲染标题：
```
font_file_id
```
、
```
font_weight: 700
```
、
```
font_size: 160
```
、
```
color: "#FFF4E0"
```
，画布为 1200 x 240。如果渲染被拒绝，读取所需尺寸并扩大画布。
使用
```
#1A0F08
```
再次渲染相同标题，作为阴影。
使用
```
render_text
```
渲染 CTA：
```
font_size: 56
```
、
```
background_color: "#000000B3"
```
用于创建半透明底板，画布为 640 x 112。
使用
```
compose_image
```
叠加四个图层，顺序从底部开始：主视觉不设置锚点；阴影层设置
```
top: 124
```
、
```
left: 364
```
、宽度 1200、高度 240；标题层设置
```
top: 120
```
、
```
left: 360
```
并覆盖在阴影上；CTA 层设置
```
bottom: 96
```
、
```
left: 640
```
、宽度 640、高度 112；每个文字图层均使用
```
fit_and_pad
```
。
按照用户最终交付素材的尺寸查看结果。此流程没有任何步骤消耗 Creative Units，因此无需预估；汇报结果时应说明这一点。

Common mistakes

常见错误

Rerolling a generation to fix a misspelled word instead of setting the text.
Substituting a named family for the brand font without telling the user.
A canvas far from the final text box, so the type is scaled soft or thin.
Shrinking
```
font_size
```
until refused text fits, rather than resizing the box or the copy.
Expecting an outline, gradient or glow from
```
render_text
```
; it sets flat colour only.
```
stretch
```
on a text layer, which distorts the letterforms.
Text against the frame edge or over the busiest region of the art.
Flattening text into the art when the asset will be localised later.

为了修复拼写错误的单词而重新滚动生成，而不是直接设置文字。
在未告知用户的情况下，用指定字体家族替代品牌字体。
画布尺寸与最终文字框相差过大，导致文字缩放后变模糊或字重过细。
不断缩小
```
font_size
```
直到被拒绝的文字能够容纳，而不是调整画布尺寸或缩短文案。
期待
```
render_text
```
输出描边、渐变或光晕；它只能设置扁平颜色。
对文字图层使用
```
stretch
```
，导致字形变形。
将文字放在画面边缘，或覆盖在画面最繁忙的区域上。
在素材后续需要本地化时，将文字直接扁平化到画面中。