修正外部 API 文档对 style 的透传表述
db6dbfaf9 在两处英文 skill 文档里把 style 的不变式写成了「提示词与你发的
内容逐字一致」。基准错了:真正的不变式是「与同一请求省略 style 时逐字一致」
——说的是 style 不参与提示词构造,不是服务端不加工输入。
三条路径没有一条满足绝对透传:普通图片的 prompt 先 trim(紧接着的空值校验
依赖它),character 被 build_editor_character_image_prompt 包进模板(其中的
纯色背景子句是 bgfilter 抠图的依据),图标图集根本没有 prompt 字段,提示词
由 trim 过的 iconDescriptions 组装。
因此改措辞而不是改功能——三处加工都不是缺陷,实现绝对透传反而会破坏抠图和
空值校验。api-selection.md 另加一条正面说明服务端会如何加工输入,并给出各自
的原因,避免后来者误以为模板可以去掉。
中文侧五处和 OpenAPI 两处原本用的就是相对基准,未改动;代码零改动。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -115,7 +115,7 @@ python3 .codex/skills/genarrative-external-editor-api/scripts/genarrative_extern
|
||||
|
||||
## Request Patterns
|
||||
|
||||
For image and icon generation, the request-body top-level `style` field both appends a server-side pixel-art clause to the prompt sent to the provider and enables deterministic post-processing. It is distinct from `generationInputs.artSpec.style`, which is stored metadata describing the requested visual language. Pass `style="pixelArt"` in Python or `"style": "pixelArt"` in JSON to enable both on supported generation types; use `"none"` or omit the field otherwise, in which case the submitted prompt is byte-for-byte what you sent. Verify compatibility and fallback semantics in `references/api-selection.md`.
|
||||
For image and icon generation, the request-body top-level `style` field both appends a server-side pixel-art clause to the prompt sent to the provider and enables deterministic post-processing. It is distinct from `generationInputs.artSpec.style`, which is stored metadata describing the requested visual language. Pass `style="pixelArt"` in Python or `"style": "pixelArt"` in JSON to enable both on supported generation types; use `"none"` or omit the field otherwise, in which case the submitted prompt is identical to what the same request would send with the field omitted. That is not the same as passing your text through untouched — see `references/api-selection.md`, which also covers compatibility and fallback semantics.
|
||||
|
||||
For Python callers, prefer:
|
||||
|
||||
|
||||
@@ -88,7 +88,8 @@ Ask a follow-up only when two routes could both be correct and produce different
|
||||
|
||||
The request-body top-level `style` field controls both the prompt actually submitted to the provider and deterministic image post-processing. It is separate from `generationInputs.artSpec.style`, which is stored metadata describing the requested visual language.
|
||||
|
||||
- Omitted, `null`, an empty string, and `"none"` all disable post-processing without a warning, and leave the submitted prompt byte-for-byte as you sent it.
|
||||
- Omitted, `null`, an empty string, and `"none"` all disable post-processing without a warning, and leave the submitted prompt identical to what the same request would send with the field omitted.
|
||||
- That guarantee is about this field only, not about passthrough of your text. The server always builds the submitted prompt: ordinary image prompts are trimmed, `kind: "character"` prompts are wrapped in a server-side template that pins the flat key-colour background matting depends on, and icon spritesheet generation has no `prompt` field at all — its prompt is assembled from the trimmed `iconDescriptions`. `style` does not participate in any of that.
|
||||
- `"pixelArt"` appends one server-side clause to the end of the submitted prompt and enables deterministic pixel-art snapping, for ordinary image generation (omit `kind`), `kind: "character"`, and icon spritesheet generation. The clause is scoped per path — `画面为像素风格` for ordinary images, `角色主体为像素风格` for characters, and `每个图标素材均为像素风格` for icon spritesheets. Character and icon spritesheet generation are matted against a flat key-colour background afterwards, so their clauses deliberately never demand a whole-canvas pixelation that would fight the flat-background requirement already in those prompts.
|
||||
- Unknown strings, or `"pixelArt"` on unsupported image kinds such as `spec`, `quick-edit`, `ui-design`, or `publication-material`, continue without style processing and return `warning.code: "unsupported-image-style"`.
|
||||
- A non-string JSON value is malformed and returns HTTP `400`. Keep the field extensible; do not treat the current examples as a closed client-side enum.
|
||||
|
||||
Reference in New Issue
Block a user