pi-tsgw 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -6
- package/extensions/images/README.md +65 -23
- package/extensions/images/adapter.ts +31 -48
- package/extensions/images/image-data.ts +228 -0
- package/extensions/images/parameters.ts +136 -0
- package/extensions/images/request.ts +102 -0
- package/extensions/images/response.ts +34 -47
- package/extensions/images/stream-response.ts +180 -0
- package/extensions/images/tool-files.ts +156 -0
- package/extensions/images/tool-schema.ts +73 -0
- package/extensions/images/tools.ts +98 -0
- package/extensions/models/vendors/openai.ts +2 -2
- package/index.ts +6 -1
- package/package.json +3 -3
- package/skills/tsgw-delegate-model-selection/SKILL.md +3 -2
- package/skills/tsgw-image-generation/SKILL.md +150 -0
package/README.md
CHANGED
|
@@ -142,13 +142,18 @@ Pi 1.2+ 可在现有 `tsgw` provider 中注册 `gpt-image-2.5-flare` 和
|
|
|
142
142
|
`gpt-image-2.5` 或其他图片模型。需要按前缀纳入时可用 `"includeModels": ["gpt-image-2.5*"]`,
|
|
143
143
|
但 include 不能突破目录交集。
|
|
144
144
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
145
|
+
图片能力提供两个直接工具:`tsgw_generate_image` 从文字生成图片,`tsgw_edit_image` 使用原图和可选蒙版编辑。
|
|
146
|
+
它们共用宿主 `modelRegistry.generateImages()` 和同一图片适配器,不要求启用 codemode。
|
|
147
|
+
默认使用 Sunburst 生成一张 PNG,草稿任务可选 Flare;质量、尺寸、格式、压缩、数量、背景及流式参数可按需覆盖。
|
|
148
|
+
工具返回图片和保存原始字节的临时路径;编辑支持本地文件、图片 URL/data URI 或上游文件 ID。
|
|
149
|
+
图片模型不进入聊天选择器或搜索代理。原生 codemode 调用仍可用;调用、文件权限、超时及结果边界见
|
|
150
|
+
[图片生成维护与使用说明](extensions/images/README.md)。
|
|
151
|
+
|
|
152
|
+
随包 [tsgw-image-generation](skills/tsgw-image-generation/SKILL.md) 技能提供生成、编辑、模型选型和参数示例;
|
|
153
|
+
可以直接描述需要的图片,也可使用 `/skill:tsgw-image-generation` 显式加载技能。
|
|
149
154
|
|
|
150
155
|
图片价格显示为 0 表示尚未映射准确价格,不是免费;usage 只统计上游已报告的有效 tokens。
|
|
151
|
-
|
|
156
|
+
隔离测试不替代真实网关对各参数、编辑、流式和图片展示的逐项验收。
|
|
152
157
|
|
|
153
158
|
## 状态栏与会话控制
|
|
154
159
|
|
|
@@ -203,6 +208,7 @@ Pi Web 可能要等会话运行时启动后才显示扩展状态。
|
|
|
203
208
|
|
|
204
209
|
| 技能 | 用途 |
|
|
205
210
|
| --- | --- |
|
|
211
|
+
| [tsgw-image-generation](skills/tsgw-image-generation/SKILL.md) | 通过两个图片工具生成或编辑图片,按草稿/成稿选择模型,并说明默认值和完整可选参数。 |
|
|
206
212
|
| [tsgw-git-commit](skills/tsgw-git-commit/SKILL.md) | 暂存内容核验、分批提交与中文提交说明;包含支持 worktree 的只读仓库发现脚本。 |
|
|
207
213
|
| [tsgw-github](skills/tsgw-github/SKILL.md) | 使用 gh 查询与维护 issue、PR、CI,安全发布正文并核验 Actions 升级。 |
|
|
208
214
|
| [tsgw-mk-docs](skills/tsgw-mk-docs/SKILL.md) | 需求、设计、执行计划、术语和状态证据的文档治理,含参考清单与模板,不依赖审阅插件。 |
|
|
@@ -228,7 +234,7 @@ GLM 指导使用 5.3,并以 Flash 和 FlashX 为备选。思考级别使用 Pi
|
|
|
228
234
|
包设置中的 `skills: []` 可禁用全部技能,`skills: ["skills/tsgw-git-commit"]` 可仅加载指定技能,
|
|
229
235
|
或用 `skills: ["!skills/tsgw-git-commit/**"]` 排除该技能;由宿主处理,不是 `tsgw` 配置项。
|
|
230
236
|
|
|
231
|
-
|
|
237
|
+
模型选型技能需要宿主提供支持模型选择的子代理工具及可用的 `tsgw` 模型;图片生成技能需要 Pi 1.2+、图片工具与可用的 `tsgw` 图片模型。通用开发技能不绑定模型 provider。
|
|
232
238
|
本包不提供子代理工具,也不改变调度设置、用户规则文件或宿主权限。
|
|
233
239
|
|
|
234
240
|
### 记忆规则注入
|
|
@@ -1,39 +1,81 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 图片生成与编辑
|
|
2
2
|
|
|
3
|
-
本目录维护 `tsgw`
|
|
4
|
-
此功能使用 Pi 的 `type: image` 模型与 codemode 图片 API,不是聊天模型、MCP 服务或图片编辑功能。
|
|
3
|
+
本目录维护 `tsgw` 的原生图片适配及两个直接工具。两者都复用 Pi 模型注册表、供应商认证与同一套请求/响应实现,不另建凭据解析或 HTTP SDK。
|
|
5
4
|
|
|
6
|
-
##
|
|
5
|
+
## 入口与模型
|
|
7
6
|
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
7
|
+
- `tsgw_generate_image`:从文字生成图片,只有 `prompt` 必填。
|
|
8
|
+
- `tsgw_edit_image`:根据 `prompt` 和 `images` 编辑图片,`mask` 可选且对应第一张参考图。
|
|
9
|
+
- 两个工具默认直接向模型声明,不要求启用 codemode;仅 Pi 1.2.0 或更高稳定版登记,旧宿主保持聊天能力,不提高最低 peer。
|
|
10
|
+
- 只登记 `gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 两款 `type: image` 模型,输入为文本/图片,输出为图片。草稿/速度优先选 Flare,成稿/质量优先选 Sunburst;工具默认 Sunburst,不自动选择另一型号重试。
|
|
11
|
+
- 图片目录仍取静态目录与网关目录的交集,再应用 include/exclude。`includeModels: ["gpt-image-2.5*"]` 不能突破交集;图片不进入聊天模型选择器或联网代理候选。
|
|
11
12
|
|
|
12
|
-
|
|
13
|
+
工具输入示例及完整可选参数表见随包[图片技能](../../skills/tsgw-image-generation/SKILL.md)。技能用于任务选型与参数使用,不代替实际工具执行。
|
|
13
14
|
|
|
14
|
-
|
|
15
|
+
## 请求与参数
|
|
15
16
|
|
|
16
|
-
|
|
17
|
+
生成使用 `POST /v1/images/generations`;编辑使用 `POST /v1/images/edits` 的 JSON `images[]` / `mask` 引用形式。不创建上游 Files 对象,不自动改用 multipart 重试。两种请求沿用 provider 的 `baseUrl`,由宿主解析现有 TSGW 认证并传入 `options.apiKey`。
|
|
17
18
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
默认值是使用便利,不是功能限制:
|
|
20
|
+
|
|
21
|
+
- `quality`、`size`、`background`、`moderation` 默认 `auto`;`n` 默认 1,可选 1–10。
|
|
22
|
+
- `output_format` 默认 `png`,也支持 `jpeg` / `webp`;JPEG/WebP 可用 `output_compression: 0..100`,省略采用上游默认 100。PNG 不发送压缩参数,透明背景不能配 JPEG。
|
|
23
|
+
- `quality` 支持 `auto/low/medium/high/xhigh/max`。尺寸支持 auto 或符合上游边长、像素、16 倍数和宽高比条件的 `宽x高`;超过 3686400 像素为上游实验范围。
|
|
24
|
+
- `stream` 默认 false;`partial_images` 默认 0,仅流式时可指定 0–3。流式响应中的过程图不计作额外生成图;当前接口返回最终图片,不承诺 Pi Web 渐进预览。
|
|
25
|
+
- `safety_identifier` 默认省略,最多 128 字符;`user` 仅为上游废弃字段兼容保留。不自动采集或生成用户身份。
|
|
26
|
+
- `response_format`、`style`、`standard/hd` 是旧模型字段或取值,不混入这两款能力;`input_fidelity` 没有两款 2.5 的明确支持证据,不据共享 schema 自动开放。
|
|
27
|
+
|
|
28
|
+
未知参数、无效取值和冲突组合在请求前报错。`onPayload` 可改变有效参数,序列化后仍核对实际发送内容和端点边界,不允许换模型、把生成悄悄变成编辑或绕过验证。
|
|
29
|
+
|
|
30
|
+
## 原图、蒙版与本地权限
|
|
31
|
+
|
|
32
|
+
每个 `images[]` 或 `mask` 来源必须且只能选择一种:
|
|
33
|
+
|
|
34
|
+
- `{ path: "source.png" }`:Pi 主机本地普通文件,相对路径按 `ctx.cwd` 解析;直接读取原始字节,不经内置 `read` 的缩放或转码。
|
|
35
|
+
- `{ image_url: "https://…" }`:无用户名密码的 HTTP(S) URL,或 PNG/JPEG/WebP 的 base64 data URI。
|
|
36
|
+
- `{ file_id: "file-…" }`:调用方已有的上游图片文件 ID。
|
|
37
|
+
|
|
38
|
+
参考图 1–16 张,保持顺序。蒙版不占参考图张数;可读取的蒙版须有 alpha 通道,并与第一张图的尺寸、格式匹配。
|
|
39
|
+
|
|
40
|
+
本地文件和内联图片每个严格小于 50 MB,参考图与蒙版合计不超过 100 MB;这是插件资源预算,不代表上游最大业务容量。只读普通文件,核对读取前后身份与大小;不修改输入、不转码或丢弃透明通道。URL/file_id 交上游解析,不在插件内下载,无法本地检查的尺寸/蒙版条件由上游验证。
|
|
41
|
+
|
|
42
|
+
文件读取及外传由图片工具整体和宿主工具钩子控制,使用 Pi 进程的操作系统权限,**不等于内置 read 的审批或文件沙箱**。输入引用可能含临时签名,结果和普通错误不复述这些值。
|
|
43
|
+
|
|
44
|
+
## 原生程序化入口
|
|
45
|
+
|
|
46
|
+
原生 `models.generateImages(model, context)` 仍可用,只有两个参数。`context.tsgw` 是本插件增加的供应商参数,不是 Pi 通用 ImagesContext 的标准字段;TypeScript 调用方可使用 `TsgwImagesContext` 类型。
|
|
47
|
+
|
|
48
|
+
```js
|
|
49
|
+
// @options: {"timeout_ms": 660000}
|
|
50
|
+
const model = await models.getModelOfType("image", "tsgw", "gpt-image-2.5-sunburst");
|
|
22
51
|
const result = await models.generateImages(model, {
|
|
23
52
|
input: [{ type: "text", text: "横版水墨山水,远山薄雾,一叶扁舟,不要文字" }],
|
|
53
|
+
tsgw: { quality: "high", size: "1536x1024", output_format: "webp", output_compression: 85 },
|
|
24
54
|
});
|
|
25
55
|
if (result.stopReason !== "stop") throw new Error(result.errorMessage);
|
|
26
|
-
const
|
|
27
|
-
if (pictures.length === 0) throw new Error("没有返回图片,不视为生成成功");
|
|
28
|
-
for (const block of pictures) image(block);
|
|
56
|
+
for (const block of result.output) if (block.type === "image") image(block);
|
|
29
57
|
```
|
|
30
58
|
|
|
31
|
-
|
|
59
|
+
原生 `input` 的图片块用于参考图编辑,也可使用 `tsgw.images` 的上游引用;两者不能同时提供。显式 `tsgw.operation` 为 `generate` / `edit`,省略时按是否有参考图决定;工具始终明确指定操作。蒙版通过 `tsgw.mask` 提供。原生调用不直接读取本地 path,读取原文件由工具层负责。
|
|
60
|
+
|
|
61
|
+
codemode 原生桥接不传第三参数,不会通过修改 model 对象转发参数。宿主 SDK 的 `ctx.modelRegistry.generateImages()` 仍可在 options 中传 `timeoutMs`、signal 和钩子。
|
|
62
|
+
|
|
63
|
+
## 超时、输出与用量
|
|
64
|
+
|
|
65
|
+
请求默认 600000ms,可通过工具的 `timeout_ms` 或 SDK 的 `options.timeoutMs` 显式缩短或延长,最大不超过 Node timer 范围。codemode 包装脚本应留余量,例如默认请求配 660000ms;它不是请求超时参数。取消、超时或失败都不自动重试或改用其他模型,也不保证上游停止处理或计费。
|
|
66
|
+
|
|
67
|
+
成功结果包含实际图片块和原始文件临时路径。原始文件以唯一临时目录、排他创建写入,不覆盖用户文件;保存失败保留上游用量及可用图片,明确区别“生成成功但保存失败”。预览进入会话后可能由宿主缩放/转码;后续精确编辑应使用保存的原始文件。
|
|
68
|
+
|
|
69
|
+
响应读取有界:普通 JSON 按每张 32 MiB 预算扩展,流式按单事件 32 MiB 及总流预算控制。返回图片单边不超过 3840,总像素不超过 8294400。PNG/JPEG/WebP 校验容器、必要头、尺寸等;PNG 保留 CRC 验证,不声称完整解码压缩像素流。JPEG 接受常见 Huffman 顺序/渐进编码,WebP 不接受动画容器。
|
|
70
|
+
|
|
71
|
+
usage 仅取上游报告的有效 tokens;坏图、断流等失败路径仍尽量保留已报告用量。多图 SSE 的逐事件用量是否共享、累计或重复汇总尚无明确契约,工具以 `usage_reports` 保留有效报告并标注 `usage_note`,不相加、不当作请求总量计入会话,也不因计量不明而丢弃有效图片;原生结果以 `tsgwUsage` 携带此扩展信息。图片价格 0 表示未映射准确价格,不表示免费。模型登记、参数注入和合成 SDK 测试都不等于真实端点、全部组合或 UI 行为验收。
|
|
32
72
|
|
|
33
|
-
|
|
73
|
+
## 维护与验证
|
|
34
74
|
|
|
35
|
-
|
|
36
|
-
|
|
75
|
+
- `tools.ts` / `tool-schema.ts` / `tool-files.ts`:工具、参数声明、原图与输出文件。
|
|
76
|
+
- `parameters.ts` / `request.ts`:参数、引用、生成/编辑请求及最终序列化验证。
|
|
77
|
+
- `adapter.ts`:宿主凭据、HTTP、钩子与取消/超时。
|
|
78
|
+
- `response.ts` / `image-data.ts` / `stream-response.ts`:用量、格式校验、普通/流式响应。
|
|
79
|
+
- `host-integration.test.ts`:原生模型与 codemode 回归;`tools-host.test.ts`:无 codemode 的真实 SDK 工具回归,HTTP 使用隔离 fixture。
|
|
37
80
|
|
|
38
|
-
|
|
39
|
-
`models.ts` 汇出图片入口并判断宿主基线,`adapter.ts` / `response.ts` 负责图片请求及结果校验。
|
|
81
|
+
接口与模型证据见记忆系统 942;用户确认网关编辑端点兼容,不替代本插件新组合的独立验收。测试不读取个人配置或请求真实网关,真实推理另需授权。
|
|
@@ -1,35 +1,13 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { ProviderHeaders, ProviderImages } from "@earendil-works/pi-ai";
|
|
2
2
|
import { IMAGE_API, IMAGE_MODEL_IDS } from "./models.ts";
|
|
3
|
-
import { abortable, ImageFailure,
|
|
3
|
+
import { abortable, ImageFailure, parseUsage, record } from "./response.ts";
|
|
4
|
+
import type { TsgwImagesResult } from "./parameters.ts";
|
|
5
|
+
import { createImageRequest, serializeImageRequest } from "./request.ts";
|
|
6
|
+
import { readImageResponse } from "./stream-response.ts";
|
|
4
7
|
|
|
5
|
-
const DEFAULT_TIMEOUT_MS =
|
|
8
|
+
const DEFAULT_TIMEOUT_MS = 600_000;
|
|
9
|
+
const MAX_TIMEOUT_MS = 2_147_483_647;
|
|
6
10
|
const UNCERTAIN = "未自动重试;此结果不代表上游未计费。";
|
|
7
|
-
const QUALITIES = new Set(["low", "medium", "high", "xhigh", "max", "auto"]);
|
|
8
|
-
|
|
9
|
-
function validPrompt(value: unknown): value is string {
|
|
10
|
-
return typeof value === "string" && value.trim().length > 0 && value.length <= 32_000;
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
function validSize(value: unknown): boolean {
|
|
14
|
-
if (value === "auto") return true;
|
|
15
|
-
if (typeof value !== "string" || /^[1-9]\d{0,3}x[1-9]\d{0,3}$/.exec(value)?.[0] !== value) return false;
|
|
16
|
-
const [width, height] = value.split("x").map(Number);
|
|
17
|
-
return width % 16 === 0 && height % 16 === 0 && Math.max(width, height) <= 3840 &&
|
|
18
|
-
Math.max(width, height) / Math.min(width, height) <= 3 &&
|
|
19
|
-
width * height >= 655_360 && width * height <= 8_294_400;
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
function payloadBody(payload: unknown, id: string): string {
|
|
23
|
-
// 校验实际发送的 JSON,避免钩子对象的 getter/toJSON 绕过固定请求边界。
|
|
24
|
-
const body = JSON.stringify(payload);
|
|
25
|
-
const value: unknown = body === undefined ? undefined : JSON.parse(body);
|
|
26
|
-
if (!record(value) || value.model !== id || value.n !== 1 || value.output_format !== "png" ||
|
|
27
|
-
!validPrompt(value.prompt) || typeof value.quality !== "string" || !QUALITIES.has(value.quality) || !validSize(value.size)) {
|
|
28
|
-
throw new ImageFailure("图片请求参数无效:仅允许当前模型、单张 PNG、非空且不超过 32000 字符的提示词及受限质量和尺寸。");
|
|
29
|
-
}
|
|
30
|
-
return body;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
11
|
function mergeHeaders(apiKey: string | undefined, ...sources: (ProviderHeaders | undefined)[]): Headers {
|
|
34
12
|
const headers = new Headers({ "Content-Type": "application/json" });
|
|
35
13
|
if (apiKey?.trim()) headers.set("Authorization", `Bearer ${apiKey}`);
|
|
@@ -47,7 +25,7 @@ function mergeHeaders(apiKey: string | undefined, ...sources: (ProviderHeaders |
|
|
|
47
25
|
}
|
|
48
26
|
|
|
49
27
|
export const generateImages: ProviderImages["generateImages"] = async (model, context, options = {}) => {
|
|
50
|
-
const result:
|
|
28
|
+
const result: TsgwImagesResult = {
|
|
51
29
|
api: IMAGE_API, provider: "tsgw", model: model.id, output: [], stopReason: "error", timestamp: Date.now(),
|
|
52
30
|
};
|
|
53
31
|
const controller = new AbortController();
|
|
@@ -66,26 +44,21 @@ export const generateImages: ProviderImages["generateImages"] = async (model, co
|
|
|
66
44
|
check();
|
|
67
45
|
if (model.type !== "image" || model.provider !== "tsgw" || model.api !== IMAGE_API ||
|
|
68
46
|
!IMAGE_MODEL_IDS.some(id => id === model.id)) throw new ImageFailure("不支持此图片模型或协议。");
|
|
69
|
-
if (!Array.isArray(context.input) || context.input.length === 0 ||
|
|
70
|
-
context.input.some(block => !block || block.type !== "text" || !validPrompt(block.text))) {
|
|
71
|
-
throw new ImageFailure("图片生成仅接受非空文本块,不接受图片或空输入。");
|
|
72
|
-
}
|
|
73
|
-
const prompt = context.input.map(block => block.type === "text" ? block.text : "").join("\n");
|
|
74
|
-
if (!validPrompt(prompt)) throw new ImageFailure("图片提示词合并后不得超过 32000 字符。");
|
|
75
47
|
const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
76
|
-
if (!Number.isFinite(timeout) || timeout < 0) throw new ImageFailure("图片请求超时时间无效。");
|
|
77
|
-
const duration =
|
|
48
|
+
if (!Number.isFinite(timeout) || timeout < 0 || timeout > MAX_TIMEOUT_MS) throw new ImageFailure("图片请求超时时间无效。");
|
|
49
|
+
const duration = timeout;
|
|
78
50
|
deadline = Date.now() + duration;
|
|
79
51
|
timer = setTimeout(() => {
|
|
80
52
|
if (!controller.signal.aborted) { timedOut = true; controller.abort(); }
|
|
81
53
|
}, duration);
|
|
82
54
|
check();
|
|
83
|
-
const
|
|
55
|
+
const { operation, payload } = createImageRequest(context, result.model);
|
|
56
|
+
check();
|
|
57
|
+
const url = `${model.baseUrl.replace(/\/+$/, "")}/images/${operation === "edit" ? "edits" : "generations"}`;
|
|
84
58
|
const headers = mergeHeaders(options.apiKey, model.headers, options.headers);
|
|
85
|
-
const payload = { model: result.model, prompt, n: 1, quality: "auto", size: "auto", output_format: "png" };
|
|
86
59
|
const replacement = options.onPayload ? await abortable(controller.signal, () => options.onPayload!(payload, model)) : undefined;
|
|
87
60
|
check();
|
|
88
|
-
const body =
|
|
61
|
+
const { body, expected } = serializeImageRequest(replacement === undefined ? payload : replacement, result.model, operation);
|
|
89
62
|
check();
|
|
90
63
|
const response = await abortable(controller.signal, async () => {
|
|
91
64
|
const response = await (options.fetch ?? globalThis.fetch)(url, {
|
|
@@ -107,14 +80,24 @@ export const generateImages: ProviderImages["generateImages"] = async (model, co
|
|
|
107
80
|
const status = Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? `(HTTP ${response.status})` : "";
|
|
108
81
|
throw new ImageFailure(`图片请求失败${status}。`);
|
|
109
82
|
}
|
|
110
|
-
const
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
83
|
+
const output = await readImageResponse(response, controller.signal, expected, raw => {
|
|
84
|
+
// 上游可能已完成计费;坏图、断流或取消也保留已报告且有效的用量。
|
|
85
|
+
if (record(raw) && Array.isArray(raw.usage_reports)) {
|
|
86
|
+
delete result.usage;
|
|
87
|
+
const reports = raw.usage_reports.slice(0, 10).flatMap(report => {
|
|
88
|
+
const usage = parseUsage({ usage: report }, model);
|
|
89
|
+
if (!usage) return [];
|
|
90
|
+
const { input, output, cacheRead, cacheWrite, totalTokens } = usage;
|
|
91
|
+
return [{ input, output, cacheRead, cacheWrite, totalTokens }];
|
|
92
|
+
});
|
|
93
|
+
result.tsgwUsage = { status: "unaggregated", reports };
|
|
94
|
+
} else {
|
|
95
|
+
const usage = parseUsage(raw, model);
|
|
96
|
+
if (usage && !result.tsgwUsage) result.usage = usage;
|
|
97
|
+
}
|
|
98
|
+
});
|
|
116
99
|
check();
|
|
117
|
-
result.output =
|
|
100
|
+
result.output = output;
|
|
118
101
|
result.stopReason = "stop";
|
|
119
102
|
return result;
|
|
120
103
|
} catch (error) {
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
// 仅检查容器、必要头和尺寸,不解压或解码像素;不保证压缩像素流可完整解码。
|
|
2
|
+
// 仅此类携带插件自行构造的安全错误;原始异常和服务端消息不进入结果。
|
|
3
|
+
export class ImageFailure extends Error {}
|
|
4
|
+
export type ImageFormat = "png" | "jpeg" | "webp";
|
|
5
|
+
export interface InspectedImage {
|
|
6
|
+
data: string;
|
|
7
|
+
mimeType: "image/png" | "image/jpeg" | "image/webp";
|
|
8
|
+
width: number;
|
|
9
|
+
height: number;
|
|
10
|
+
hasAlpha: boolean;
|
|
11
|
+
}
|
|
12
|
+
type Dimensions = Pick<InspectedImage, "width" | "height" | "hasAlpha">;
|
|
13
|
+
const invalid = (): never => { throw new ImageFailure("图片不是有效的 canonical base64 PNG、JPEG 或 WebP 容器。"); };
|
|
14
|
+
const crcTable = Array.from({ length: 256 }, (_, n) => {
|
|
15
|
+
for (let bit = 0; bit < 8; bit++) n = (n >>> 1) ^ ((n & 1) ? 0xedb88320 : 0);
|
|
16
|
+
return n >>> 0;
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
function png(bytes: Buffer): Dimensions {
|
|
20
|
+
if (bytes.length < 57) return invalid();
|
|
21
|
+
let offset = 8, idat = false, endedIdat = false, palette = 0, transparency = false;
|
|
22
|
+
let width = 0, height = 0, color = -1, depth = 0;
|
|
23
|
+
while (offset + 12 <= bytes.length) {
|
|
24
|
+
const length = bytes.readUInt32BE(offset), end = offset + 12 + length;
|
|
25
|
+
if (length > 0x7fffffff || end > bytes.length) return invalid();
|
|
26
|
+
const type = bytes.toString("latin1", offset + 4, offset + 8);
|
|
27
|
+
if (!/^[A-Za-z]{4}$/.test(type) || type[2] !== type[2].toUpperCase()) return invalid();
|
|
28
|
+
let crc = 0xffffffff;
|
|
29
|
+
for (let i = offset + 4; i < end - 4; i++) crc = (crc >>> 8) ^ crcTable[(crc ^ bytes[i]) & 255];
|
|
30
|
+
if (((crc ^ 0xffffffff) >>> 0) !== bytes.readUInt32BE(end - 4)) return invalid();
|
|
31
|
+
const start = offset + 8;
|
|
32
|
+
if (offset === 8) {
|
|
33
|
+
if (type !== "IHDR" || length !== 13) return invalid();
|
|
34
|
+
width = bytes.readUInt32BE(start); height = bytes.readUInt32BE(start + 4);
|
|
35
|
+
depth = bytes[start + 8]; color = bytes[start + 9];
|
|
36
|
+
const depths: Record<number, number[]> = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
|
|
37
|
+
if (!width || !height || width > 0x7fffffff || height > 0x7fffffff || !depths[color]?.includes(depth) ||
|
|
38
|
+
bytes[start + 10] !== 0 || bytes[start + 11] !== 0 || bytes[start + 12] > 1) return invalid();
|
|
39
|
+
} else if (type === "IHDR") return invalid();
|
|
40
|
+
if (type === "PLTE") {
|
|
41
|
+
if (palette || idat || transparency || color === 0 || color === 4 || !length || length % 3 || length > 768 ||
|
|
42
|
+
(color === 3 && length / 3 > 2 ** depth)) return invalid();
|
|
43
|
+
palette = length / 3;
|
|
44
|
+
}
|
|
45
|
+
if (type === "tRNS") {
|
|
46
|
+
if (transparency || idat || !((color === 0 && length === 2) || (color === 2 && length === 6) ||
|
|
47
|
+
(color === 3 && length > 0 && length <= palette))) return invalid();
|
|
48
|
+
transparency = true;
|
|
49
|
+
}
|
|
50
|
+
if (type === "IDAT") {
|
|
51
|
+
if (endedIdat || (color === 3 && !palette)) return invalid();
|
|
52
|
+
if (length > 0) idat = true;
|
|
53
|
+
} else if (idat) endedIdat = true;
|
|
54
|
+
if (type === "IEND") {
|
|
55
|
+
if (length || !idat || end !== bytes.length) return invalid();
|
|
56
|
+
return { width, height, hasAlpha: color === 4 || color === 6 || transparency };
|
|
57
|
+
}
|
|
58
|
+
if (type[0] === type[0].toUpperCase() && !["IHDR", "PLTE", "IDAT"].includes(type)) return invalid();
|
|
59
|
+
offset = end;
|
|
60
|
+
}
|
|
61
|
+
return invalid();
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function jpeg(bytes: Buffer): Dimensions {
|
|
65
|
+
let offset = 2, width = 0, height = 0, scan = false, entropy = false, frame = 0;
|
|
66
|
+
let components: number[] = [], quantization: number[] = [];
|
|
67
|
+
const quant = new Set<number>(), huffman = new Set<number>();
|
|
68
|
+
while (offset < bytes.length) {
|
|
69
|
+
if (bytes[offset++] !== 0xff) return invalid();
|
|
70
|
+
while (bytes[offset] === 0xff) offset++;
|
|
71
|
+
if (offset >= bytes.length) return invalid();
|
|
72
|
+
const marker = bytes[offset++];
|
|
73
|
+
if (marker === 0xd9) {
|
|
74
|
+
if (!width || !scan || !entropy || offset !== bytes.length) return invalid();
|
|
75
|
+
return { width, height, hasAlpha: false };
|
|
76
|
+
}
|
|
77
|
+
if (marker === 0x00 || marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7)) return invalid();
|
|
78
|
+
if (marker === 0x01) continue;
|
|
79
|
+
if (offset + 2 > bytes.length) return invalid();
|
|
80
|
+
const length = bytes.readUInt16BE(offset), end = offset + length;
|
|
81
|
+
if (length < 2 || end > bytes.length) return invalid();
|
|
82
|
+
const start = offset + 2;
|
|
83
|
+
if (marker === 0xdb) {
|
|
84
|
+
let at = start;
|
|
85
|
+
while (at < end) {
|
|
86
|
+
const table = bytes[at++], precision = table >> 4;
|
|
87
|
+
if (precision > 1 || (table & 15) > 3) return invalid();
|
|
88
|
+
quant.add(table & 15); at += 64 * (precision + 1);
|
|
89
|
+
}
|
|
90
|
+
if (at !== end || at === start) return invalid();
|
|
91
|
+
}
|
|
92
|
+
if (marker === 0xc4) {
|
|
93
|
+
let at = start;
|
|
94
|
+
while (at < end) {
|
|
95
|
+
const table = bytes[at++];
|
|
96
|
+
if ((table >> 4) > 1 || (table & 15) > 3 || at + 16 > end) return invalid();
|
|
97
|
+
let symbols = 0, available = 1;
|
|
98
|
+
for (let i = 0; i < 16; i++) {
|
|
99
|
+
const count = bytes[at++]; symbols += count; available = available * 2 - count;
|
|
100
|
+
if (available < 0) return invalid();
|
|
101
|
+
}
|
|
102
|
+
if (!symbols || symbols > 256) return invalid();
|
|
103
|
+
at += symbols; huffman.add(table);
|
|
104
|
+
}
|
|
105
|
+
if (at !== end || at === start) return invalid();
|
|
106
|
+
}
|
|
107
|
+
if (marker === 0xdd && length !== 4) return invalid();
|
|
108
|
+
if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
|
|
109
|
+
// 接受常见的 Huffman 顺序/渐进 JPEG;其他编码不冒充已验证。
|
|
110
|
+
if (width || length < 11 || ![0xc0, 0xc1, 0xc2].includes(marker)) return invalid();
|
|
111
|
+
frame = marker;
|
|
112
|
+
const precision = bytes[start], count = bytes[start + 5];
|
|
113
|
+
height = bytes.readUInt16BE(start + 1); width = bytes.readUInt16BE(start + 3);
|
|
114
|
+
if (!width || !height || ![8, 12].includes(precision) || !count || count > 4 || length !== 8 + 3 * count ||
|
|
115
|
+
(marker === 0xc0 && precision !== 8)) return invalid();
|
|
116
|
+
components = []; quantization = [];
|
|
117
|
+
for (let i = 0; i < count; i++) {
|
|
118
|
+
const at = start + 6 + 3 * i, id = bytes[at], sampling = bytes[at + 1];
|
|
119
|
+
if (components.includes(id) || !(sampling >> 4) || (sampling >> 4) > 4 || !(sampling & 15) ||
|
|
120
|
+
(sampling & 15) > 4 || bytes[at + 2] > 3) return invalid();
|
|
121
|
+
components.push(id); quantization.push(bytes[at + 2]);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
if (marker === 0xda) {
|
|
125
|
+
const count = bytes[start];
|
|
126
|
+
if (!width || !count || count > components.length || length !== 6 + 2 * count || quantization.some(id => !quant.has(id))) return invalid();
|
|
127
|
+
const spectral = start + 1 + 2 * count, ss = bytes[spectral], se = bytes[spectral + 1], approx = bytes[spectral + 2];
|
|
128
|
+
if (frame !== 0xc2 ? (ss !== 0 || se !== 63 || approx !== 0) :
|
|
129
|
+
(ss > se || se > 63 || (ss === 0 && se !== 0) || (ss > 0 && count !== 1) ||
|
|
130
|
+
(approx >> 4) > 13 || (approx & 15) > 13)) return invalid();
|
|
131
|
+
const selected = new Set<number>();
|
|
132
|
+
for (let i = 0; i < count; i++) {
|
|
133
|
+
const id = bytes[start + 1 + i * 2], tables = bytes[start + 2 + i * 2];
|
|
134
|
+
if (!components.includes(id) || selected.has(id) || (tables >> 4) > 3 || (tables & 15) > 3 ||
|
|
135
|
+
(ss === 0 && !(approx >> 4) && !huffman.has(tables >> 4)) || (se > 0 && !huffman.has(0x10 | (tables & 15)))) return invalid();
|
|
136
|
+
selected.add(id);
|
|
137
|
+
}
|
|
138
|
+
scan = true; entropy = false; offset = end;
|
|
139
|
+
// 扫描压缩数据中的转义/重启标记;不读取 Huffman 系数。
|
|
140
|
+
while (offset < bytes.length) {
|
|
141
|
+
if (bytes[offset] !== 0xff) { entropy = true; offset++; continue; }
|
|
142
|
+
let next = offset + 1;
|
|
143
|
+
while (bytes[next] === 0xff) next++;
|
|
144
|
+
if (next >= bytes.length) return invalid();
|
|
145
|
+
if (bytes[next] === 0 || (bytes[next] >= 0xd0 && bytes[next] <= 0xd7)) {
|
|
146
|
+
if (bytes[next] === 0) entropy = true;
|
|
147
|
+
offset = next + 1; continue;
|
|
148
|
+
}
|
|
149
|
+
break;
|
|
150
|
+
}
|
|
151
|
+
if (!entropy) return invalid();
|
|
152
|
+
} else offset = end;
|
|
153
|
+
}
|
|
154
|
+
return invalid();
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function vp8(bytes: Buffer): Dimensions {
|
|
158
|
+
if (bytes.length < 11 || (bytes[0] & 1) || ((bytes[0] >>> 1) & 7) > 3 || !(bytes[0] & 16) ||
|
|
159
|
+
!bytes.subarray(3, 6).equals(Buffer.from([0x9d, 1, 0x2a]))) return invalid();
|
|
160
|
+
const partition = bytes.readUIntLE(0, 3) >>> 5;
|
|
161
|
+
const width = bytes.readUInt16LE(6) & 0x3fff, height = bytes.readUInt16LE(8) & 0x3fff;
|
|
162
|
+
if (!width || !height || (bytes.readUInt16LE(6) & 0xc000) || (bytes.readUInt16LE(8) & 0xc000) ||
|
|
163
|
+
!partition || partition > bytes.length - 10) return invalid();
|
|
164
|
+
return { width, height, hasAlpha: false };
|
|
165
|
+
}
|
|
166
|
+
function vp8l(bytes: Buffer): Dimensions {
|
|
167
|
+
if (bytes.length < 6 || bytes[0] !== 0x2f) return invalid();
|
|
168
|
+
const bits = bytes.readUInt32LE(1);
|
|
169
|
+
if (bits >>> 29) return invalid();
|
|
170
|
+
return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1, hasAlpha: !!(bits & 0x10000000) };
|
|
171
|
+
}
|
|
172
|
+
function webp(bytes: Buffer): Dimensions {
|
|
173
|
+
if (bytes.length < 20 || bytes.readUInt32LE(4) !== bytes.length - 8) return invalid();
|
|
174
|
+
let offset = 12, image: Dimensions | undefined, canvas: Dimensions | undefined;
|
|
175
|
+
let flags = 0, alpha = false;
|
|
176
|
+
const seen = new Set<string>();
|
|
177
|
+
while (offset + 8 <= bytes.length) {
|
|
178
|
+
const type = bytes.toString("latin1", offset, offset + 4), length = bytes.readUInt32LE(offset + 4);
|
|
179
|
+
const start = offset + 8, end = start + length, padded = end + (length & 1);
|
|
180
|
+
if (padded > bytes.length || ((length & 1) && bytes[end] !== 0)) return invalid();
|
|
181
|
+
const data = bytes.subarray(start, end);
|
|
182
|
+
if (["VP8X", "VP8 ", "VP8L", "ALPH", "ICCP", "EXIF", "XMP "].includes(type)) {
|
|
183
|
+
if (seen.has(type)) return invalid();
|
|
184
|
+
seen.add(type);
|
|
185
|
+
}
|
|
186
|
+
if (type === "VP8X") {
|
|
187
|
+
if (offset !== 12 || length !== 10 || data[0] & 0xc3 || data[1] || data[2] || data[3]) return invalid();
|
|
188
|
+
flags = data[0];
|
|
189
|
+
// 不支持动画容器,避免只验证画布却展示未检查的动画帧。
|
|
190
|
+
if (flags & 2) return invalid();
|
|
191
|
+
canvas = { width: data.readUIntLE(4, 3) + 1, height: data.readUIntLE(7, 3) + 1, hasAlpha: !!(flags & 16) };
|
|
192
|
+
if (canvas.width * canvas.height > 0xffffffff) return invalid();
|
|
193
|
+
} else if (type === "ANIM" || type === "ANMF") return invalid();
|
|
194
|
+
else if (type === "ALPH") {
|
|
195
|
+
if (!canvas || !(flags & 16) || image || length < 2 || data[0] & 0xc0 || (data[0] & 3) > 1 ||
|
|
196
|
+
((data[0] >>> 4) & 3) > 1) return invalid();
|
|
197
|
+
if (!(data[0] & 3) && length !== 1 + canvas.width * canvas.height) return invalid();
|
|
198
|
+
alpha = true;
|
|
199
|
+
} else if (type === "VP8 " || type === "VP8L") {
|
|
200
|
+
if (image || (type === "VP8L" && alpha)) return invalid();
|
|
201
|
+
image = type === "VP8 " ? vp8(data) : vp8l(data);
|
|
202
|
+
if (canvas && (image.width !== canvas.width || image.height !== canvas.height)) return invalid();
|
|
203
|
+
} else if (!canvas) return invalid();
|
|
204
|
+
offset = padded;
|
|
205
|
+
}
|
|
206
|
+
if (offset !== bytes.length || !image || (canvas && canvas.hasAlpha !== (alpha || image.hasAlpha)) ||
|
|
207
|
+
(alpha && !seen.has("VP8 "))) return invalid();
|
|
208
|
+
for (const [type, bit] of [["ICCP", 32], ["EXIF", 8], ["XMP ", 4]] as const) {
|
|
209
|
+
if (seen.has(type) !== !!(flags & bit)) return invalid();
|
|
210
|
+
}
|
|
211
|
+
return { ...image, hasAlpha: alpha || image.hasAlpha };
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
export function inspectImage(data: unknown, expectedFormat?: ImageFormat): InspectedImage {
|
|
215
|
+
if (typeof data !== "string" || !data.length || data.length % 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) return invalid();
|
|
216
|
+
const bytes = Buffer.from(data, "base64");
|
|
217
|
+
if (bytes.toString("base64") !== data) return invalid();
|
|
218
|
+
let format: ImageFormat, dimensions: Dimensions;
|
|
219
|
+
if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
|
|
220
|
+
format = "png"; dimensions = png(bytes);
|
|
221
|
+
} else if (bytes[0] === 0xff && bytes[1] === 0xd8) {
|
|
222
|
+
format = "jpeg"; dimensions = jpeg(bytes);
|
|
223
|
+
} else if (bytes.toString("latin1", 0, 4) === "RIFF" && bytes.toString("latin1", 8, 12) === "WEBP") {
|
|
224
|
+
format = "webp"; dimensions = webp(bytes);
|
|
225
|
+
} else return invalid();
|
|
226
|
+
if (expectedFormat !== undefined && expectedFormat !== format) throw new ImageFailure("图片响应格式与请求不一致。");
|
|
227
|
+
return { data, mimeType: `image/${format}`, ...dimensions };
|
|
228
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import type { AssistantImages, ImagesContext, Usage } from "@earendil-works/pi-ai";
|
|
2
|
+
import { inspectImage } from "./image-data.ts";
|
|
3
|
+
import { ImageFailure } from "./response.ts";
|
|
4
|
+
|
|
5
|
+
export type ImageFormat = "png" | "jpeg" | "webp";
|
|
6
|
+
export type ImageOperation = "generate" | "edit";
|
|
7
|
+
export interface ImageReference { image_url?: string; file_id?: string }
|
|
8
|
+
|
|
9
|
+
/** 十进制字节:单张严格小于上限,参考图与蒙版合计不超过总上限。 */
|
|
10
|
+
export const MAX_IMAGE_INPUT_BYTES = 50_000_000;
|
|
11
|
+
export const MAX_IMAGE_INPUT_TOTAL_BYTES = 100_000_000;
|
|
12
|
+
|
|
13
|
+
/** context.tsgw 是插件扩展,不是 Pi 原生第三参数;API 的 null 按省略处理。 */
|
|
14
|
+
export interface TsgwImageParameters {
|
|
15
|
+
operation?: ImageOperation | null;
|
|
16
|
+
images?: ImageReference[] | null;
|
|
17
|
+
mask?: ImageReference | null;
|
|
18
|
+
quality?: "auto" | "low" | "medium" | "high" | "xhigh" | "max" | null;
|
|
19
|
+
/** auto 或宽x高:16 的倍数、边长不超过 3840、比例不超过 3、像素 655360..8294400。 */
|
|
20
|
+
size?: string | null;
|
|
21
|
+
background?: "auto" | "opaque" | "transparent" | null;
|
|
22
|
+
output_format?: ImageFormat | null;
|
|
23
|
+
output_compression?: number | null;
|
|
24
|
+
n?: number | null;
|
|
25
|
+
moderation?: "auto" | "low" | null;
|
|
26
|
+
stream?: boolean | null;
|
|
27
|
+
partial_images?: number | null;
|
|
28
|
+
safety_identifier?: string | null;
|
|
29
|
+
user?: string | null;
|
|
30
|
+
}
|
|
31
|
+
export interface TsgwImagesContext extends ImagesContext { tsgw?: TsgwImageParameters }
|
|
32
|
+
/** 多图 SSE 的逐事件用量作用域不明:保留报告,不伪造请求总量。 */
|
|
33
|
+
export type ImageUsageReport = Pick<Usage, "input" | "output" | "cacheRead" | "cacheWrite" | "totalTokens">;
|
|
34
|
+
export interface TsgwImagesResult extends AssistantImages {
|
|
35
|
+
tsgwUsage?: { status: "unaggregated"; reports: ImageUsageReport[] };
|
|
36
|
+
}
|
|
37
|
+
export type NormalizedImageParameters = TsgwImageParameters & {
|
|
38
|
+
quality: NonNullable<TsgwImageParameters["quality"]>; size: string;
|
|
39
|
+
background: NonNullable<TsgwImageParameters["background"]>; output_format: ImageFormat;
|
|
40
|
+
n: number; moderation: "auto" | "low"; stream: boolean; partial_images: number;
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
export const IMAGE_PARAMETER_KEYS = ["operation", "images", "mask", "quality", "size", "background", "output_format",
|
|
44
|
+
"output_compression", "n", "moderation", "stream", "partial_images", "safety_identifier", "user"] as const;
|
|
45
|
+
const QUALITIES = new Set(["low", "medium", "high", "xhigh", "max", "auto"]);
|
|
46
|
+
const BACKGROUNDS = new Set(["auto", "opaque", "transparent"]);
|
|
47
|
+
const FORMATS = new Set(["png", "jpeg", "webp"]);
|
|
48
|
+
const invalid = () => new ImageFailure("图片 tsgw 参数无效:请检查参数名、类型、取值范围及格式/流式组合。");
|
|
49
|
+
|
|
50
|
+
export function plainImageObject(value: unknown): value is Record<string, unknown> {
|
|
51
|
+
return value !== null && typeof value === "object" && !Array.isArray(value) &&
|
|
52
|
+
(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
|
|
53
|
+
}
|
|
54
|
+
export function validSize(value: unknown): boolean {
|
|
55
|
+
if (value === "auto") return true;
|
|
56
|
+
if (typeof value !== "string" || /^[1-9]\d{0,3}x[1-9]\d{0,3}$/.exec(value)?.[0] !== value) return false;
|
|
57
|
+
const [width, height] = value.split("x").map(Number);
|
|
58
|
+
return width % 16 === 0 && height % 16 === 0 && Math.max(width, height) <= 3840 &&
|
|
59
|
+
Math.max(width, height) / Math.min(width, height) <= 3 &&
|
|
60
|
+
width * height >= 655_360 && width * height <= 8_294_400;
|
|
61
|
+
}
|
|
62
|
+
const integer = (value: unknown, min: number, max: number): value is number =>
|
|
63
|
+
typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
|
|
64
|
+
|
|
65
|
+
/** 仅用于已校验的引用:按 canonical base64 长度与 padding 计算 decoded 字节,不再次分配图片 Buffer。 */
|
|
66
|
+
export function imageReferenceInputBytes(reference: ImageReference): number {
|
|
67
|
+
const url = reference.image_url;
|
|
68
|
+
if (!url?.startsWith("data:")) return 0;
|
|
69
|
+
return (url.length - url.indexOf(",") - 1) / 4 * 3 - (url.endsWith("==") ? 2 : url.endsWith("=") ? 1 : 0);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** 不下载 URL;data URI 保留原始图片字节,且核对声明 MIME 与容器。 */
|
|
73
|
+
export function normalizeImageReference(value: unknown): ImageReference {
|
|
74
|
+
const fail = () => new ImageFailure("图片引用无效:须提供唯一的非空 file_id 或无用户名密码的 HTTP(S)/图片 data URI。");
|
|
75
|
+
if (!plainImageObject(value) || Reflect.ownKeys(value).length !== 1 || Reflect.ownKeys(value).some(key => key !== "image_url" && key !== "file_id")) throw fail();
|
|
76
|
+
const url = Object.hasOwn(value, "image_url") ? value.image_url : undefined;
|
|
77
|
+
const file = Object.hasOwn(value, "file_id") ? value.file_id : undefined;
|
|
78
|
+
if (url !== undefined && file !== undefined) throw fail();
|
|
79
|
+
if (file !== undefined) {
|
|
80
|
+
if (typeof file !== "string" || !file.trim() || file !== file.trim() || /[\u0000-\u001f\u007f]/.test(file)) throw fail();
|
|
81
|
+
return { file_id: file };
|
|
82
|
+
}
|
|
83
|
+
if (typeof url !== "string" || !url || url !== url.trim() || /[\u0000-\u0020\u007f]/.test(url)) throw fail();
|
|
84
|
+
if (url.startsWith("data:")) {
|
|
85
|
+
const overBudget = () => new ImageFailure("单张参考图或蒙版必须小于 50000000 字节。");
|
|
86
|
+
if (url.length > Math.ceil(MAX_IMAGE_INPUT_BYTES / 3) * 4 + 128) throw overBudget();
|
|
87
|
+
const match = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]*={0,2})$/.exec(url);
|
|
88
|
+
if (!match) throw fail();
|
|
89
|
+
// 与工具单文件预算一致;输入图不施加输出尺寸上限。
|
|
90
|
+
if (imageReferenceInputBytes({ image_url: url }) >= MAX_IMAGE_INPUT_BYTES) throw overBudget();
|
|
91
|
+
inspectImage(match[2], match[1] as ImageFormat);
|
|
92
|
+
return { image_url: url };
|
|
93
|
+
}
|
|
94
|
+
let parsed: URL;
|
|
95
|
+
try { parsed = new URL(url); } catch { throw fail(); }
|
|
96
|
+
if (!/^https?:\/\//i.test(url) || /^https?:\/\/[^/?#]*@/i.test(url) || !["http:", "https:"].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password) throw fail();
|
|
97
|
+
return { image_url: parsed.href };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export function normalizeImageParameters(value: unknown): NormalizedImageParameters {
|
|
101
|
+
if (value == null) value = {};
|
|
102
|
+
if (!plainImageObject(value) || Reflect.ownKeys(value).some(key => !IMAGE_PARAMETER_KEYS.some(allowed => key === allowed))) throw invalid();
|
|
103
|
+
const source = value;
|
|
104
|
+
const get = (key: string, fallback?: unknown) => (Object.hasOwn(source, key) ? source[key] : undefined) ?? fallback;
|
|
105
|
+
const quality = get("quality", "auto"), size = get("size", "auto"), background = get("background", "auto");
|
|
106
|
+
const output_format = get("output_format", "png"), n = get("n", 1), moderation = get("moderation", "auto");
|
|
107
|
+
const stream = get("stream", false), partial_images = get("partial_images", 0);
|
|
108
|
+
if (typeof quality !== "string" || !QUALITIES.has(quality) || !validSize(size) ||
|
|
109
|
+
typeof background !== "string" || !BACKGROUNDS.has(background) || typeof output_format !== "string" || !FORMATS.has(output_format) ||
|
|
110
|
+
!integer(n, 1, 10) || (moderation !== "auto" && moderation !== "low") || typeof stream !== "boolean" ||
|
|
111
|
+
!integer(partial_images, 0, 3) || (!stream && partial_images !== 0)) throw invalid();
|
|
112
|
+
const result = { quality, size, background, output_format, n, moderation, stream, partial_images } as NormalizedImageParameters;
|
|
113
|
+
const compression = get("output_compression");
|
|
114
|
+
if (compression !== undefined) {
|
|
115
|
+
if (!integer(compression, 0, 100) || output_format === "png") throw invalid();
|
|
116
|
+
result.output_compression = compression;
|
|
117
|
+
}
|
|
118
|
+
if (background === "transparent" && output_format === "jpeg") throw invalid();
|
|
119
|
+
for (const key of ["safety_identifier", "user"] as const) {
|
|
120
|
+
const text = get(key);
|
|
121
|
+
if (text === undefined) continue;
|
|
122
|
+
if (typeof text !== "string" || (key === "safety_identifier" && text.length > 128)) throw invalid();
|
|
123
|
+
result[key] = text;
|
|
124
|
+
}
|
|
125
|
+
const operation = get("operation"), images = get("images"), mask = get("mask");
|
|
126
|
+
if (operation !== undefined) {
|
|
127
|
+
if (operation !== "generate" && operation !== "edit") throw invalid();
|
|
128
|
+
result.operation = operation;
|
|
129
|
+
}
|
|
130
|
+
if (images !== undefined) {
|
|
131
|
+
if (!Array.isArray(images) || images.length < 1 || images.length > 16) throw invalid();
|
|
132
|
+
result.images = Array.from(images, normalizeImageReference);
|
|
133
|
+
}
|
|
134
|
+
if (mask !== undefined) result.mask = normalizeImageReference(mask);
|
|
135
|
+
return result;
|
|
136
|
+
}
|