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.
@@ -0,0 +1,98 @@
1
+ import type { AssistantImages, ImageContent } from "@earendil-works/pi-ai";
2
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
3
+ import { normalizeImageParameters, type ImageOperation, type TsgwImagesContext, type TsgwImagesResult, type ImageUsageReport } from "./parameters.ts";
4
+ import { DEFAULT_IMAGE_MODEL, editImageSchema, generateImageSchema, imageToolResultSchema, prepareImageToolParameters } from "./tool-schema.ts";
5
+ import { ImageToolFileError, resolveImageSources, saveImageOutput, validateImageOutput, type ImageFileResult } from "./tool-files.ts";
6
+
7
+ export interface ImageToolDetails {
8
+ operation: ImageOperation;
9
+ model: string;
10
+ phase: "validate" | "input" | "request" | "output" | "save" | "complete";
11
+ /** unknown 包含 adapter error/aborted:只确认调用未成功,不能确认上游未处理/计费。 */
12
+ requestStatus: "not-started" | "unknown" | "failed" | "succeeded";
13
+ files: ImageFileResult[];
14
+ usage_note?: string;
15
+ usage_reports?: ImageUsageReport[];
16
+ error?: { code: string; message: string };
17
+ }
18
+
19
+ /** direct 工具复用宿主目录/过滤、认证与图片适配器;不解析凭据、不自行发 HTTP。 */
20
+ export function registerImageTools(pi: ExtensionAPI): void {
21
+ for (const operation of ["generate", "edit"] as const) {
22
+ pi.registerTool({
23
+ name: operation === "generate" ? "tsgw_generate_image" : "tsgw_edit_image",
24
+ label: operation === "generate" ? "TSGW 生成图片" : "TSGW 编辑图片",
25
+ description: (operation === "generate" ? "根据 prompt 生成图片,只需填写 prompt。" : "根据 prompt 和 images 编辑图片,可选 mask;蒙版对应第一张参考图。") +
26
+ "默认 Sunburst 用于成稿;AI 草稿任务可选 Flare(通常配 quality=low),不必为普通任务指定型号。" +
27
+ "默认 quality/size/background/moderation=auto、output_format=png、n=1、stream=false、partial_images=0、超时600000毫秒。" +
28
+ (operation === "edit" ? "本地图片以 Pi 进程操作系统权限直接只读原始字节并外传,不经过内置 read 审批,不是沙箱;仅普通文件,每个小于50 MB、含蒙版合计最多100 MB。不下载远程 URL;远程蒙版的格式与尺寸交上游验证。" : "") +
29
+ "返回实际图片块与唯一临时文件路径,不需 codemode 或 image()。请求可能计费;不自动重试或换模型,失败、取消或超时都不保证停止上游处理或未计费。",
30
+ parameters: operation === "generate" ? generateImageSchema : editImageSchema,
31
+ outputSchema: imageToolResultSchema,
32
+ exposure: "direct",
33
+ defaultActive: true,
34
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
35
+ async execute(_id, params, signal, _onUpdate, ctx) {
36
+ const details: ImageToolDetails = { operation, model: DEFAULT_IMAGE_MODEL, phase: "validate", requestStatus: "not-started", files: [] };
37
+ let usage: AssistantImages["usage"];
38
+ let images: ImageContent[] = [];
39
+ const caller = signal && ctx.signal && signal !== ctx.signal ? AbortSignal.any([signal, ctx.signal]) : signal ?? ctx.signal ?? new AbortController().signal;
40
+ try {
41
+ const prepared = prepareImageToolParameters(operation, params);
42
+ details.model = prepared.model;
43
+ caller.throwIfAborted();
44
+ const registry = ctx.modelRegistry;
45
+ if (typeof registry.getModelOfType !== "function" || typeof registry.generateImages !== "function")
46
+ throw new ImageToolFileError("unsupported-host", "图片工具需要支持 modelRegistry.getModelOfType/generateImages 的 Pi 1.2 或更新宿主。");
47
+ const model = registry.getModelOfType("image", "tsgw", prepared.model);
48
+ if (!model || model.provider !== "tsgw" || model.id !== prepared.model)
49
+ throw new ImageToolFileError("model-unavailable", "所选图片模型未在当前宿主目录中启用;不会绕过目录过滤或自动切换型号。");
50
+ details.phase = "input";
51
+ const references = operation === "edit" ? await resolveImageSources(prepared.images, prepared.mask, ctx.cwd, caller) : {};
52
+ const context: TsgwImagesContext = { input: [{ type: "text", text: prepared.prompt }],
53
+ tsgw: normalizeImageParameters({ ...prepared.parameters, operation, ...references }) };
54
+ caller.throwIfAborted();
55
+ details.phase = "request";
56
+ details.requestStatus = "unknown";
57
+ // 参数走显式 context.tsgw;timeout 是 options,不冒称 Pi 原生图片参数。
58
+ const response: TsgwImagesResult = await registry.generateImages(model, context, { timeoutMs: prepared.timeoutMs, signal: caller });
59
+ usage = response.usage;
60
+ if (response.tsgwUsage?.status === "unaggregated") {
61
+ usage = undefined;
62
+ details.usage_note = "多图流式用量归属未明确,逐事件报告未相加,也未计入会话总量;不是免费。";
63
+ details.usage_reports = response.tsgwUsage.reports.map(report => ({ ...report }));
64
+ }
65
+ if (response.stopReason !== "stop") {
66
+ details.requestStatus = "unknown";
67
+ throw new ImageToolFileError(response.stopReason === "aborted" ? "aborted" : "request-failed",
68
+ response.stopReason === "aborted" ? "图片调用已取消或超时;无法保证上游停止处理或未计费,请勿自动重试。" : "图片调用未成功;无法确认上游是否处理或计费,请勿自动重试。请检查宿主模型认证与网关;未切换模型。");
69
+ }
70
+ details.requestStatus = "succeeded";
71
+ details.phase = "output";
72
+ images = validateImageOutput(response.output, context.tsgw!.n!, context.tsgw!.output_format!);
73
+ details.phase = "save";
74
+ details.files = await saveImageOutput(images);
75
+ details.phase = "complete";
76
+ } catch (error) {
77
+ if (error instanceof ImageToolFileError) {
78
+ details.error = { code: error.code, message: error.message };
79
+ if (error.files.length) details.files = error.files;
80
+ } else {
81
+ // 不转发供应商异常、输入 URL、base64 或文件系统原始异常。
82
+ details.error = caller.aborted
83
+ ? { code: "aborted", message: details.requestStatus === "not-started" ? "图片工具已取消,尚未调用上游。" : "图片调用已取消;上游结果未知,不保证停止处理或计费,请勿自动重试。" }
84
+ : details.phase === "validate" || details.phase === "input"
85
+ ? { code: "invalid-parameters", message: "图片工具参数无效;请检查字段白名单、数值范围、图片来源与参数组合。未调用上游。" }
86
+ : { code: "request-unknown", message: "图片调用异常,无法确认上游结果或是否计费;未自动重试,请检查宿主与网关。" };
87
+ }
88
+ }
89
+ return {
90
+ content: [{ type: "text" as const, text: JSON.stringify(details) }, ...images],
91
+ details, structuredContent: { ...details, files: details.files.map(file => ({ ...file })),
92
+ ...(details.usage_reports ? { usage_reports: details.usage_reports.map(report => ({ ...report })) } : {}) }, ...(usage ? { usage } : {}),
93
+ ...(details.error ? { isError: true } : {}),
94
+ };
95
+ },
96
+ });
97
+ }
98
+ }
@@ -118,7 +118,7 @@ export const OPENAI_IMAGE_MODEL_IDS = ["gpt-image-2.5-flare", "gpt-image-2.5-sun
118
118
  export type OpenAIImageModelConfig = Extract<AnyModelConfig, { type: "image" }>;
119
119
 
120
120
  /**
121
- * 图片接口依据见记忆系统 942;仅登记本插件已实现的文生图能力,不宣称支持编辑。
121
+ * 图片接口依据见记忆系统 942;两款模型共用生成与编辑适配。
122
122
  * 价格暂未纳入计费映射,0 表示未知而非免费;不混入 openaiModels 的聊天目录。
123
123
  */
124
124
  export function openaiImageModels(root: string): OpenAIImageModelConfig[] {
@@ -126,7 +126,7 @@ export function openaiImageModels(root: string): OpenAIImageModelConfig[] {
126
126
  type: "image", id,
127
127
  name: index === 0 ? "GPT Image 2.5 Flare" : "GPT Image 2.5 Sunburst",
128
128
  api: OPENAI_IMAGE_API, baseUrl: `${root}/v1`,
129
- input: ["text"], output: ["image"],
129
+ input: ["text", "image"], output: ["image"],
130
130
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
131
131
  }));
132
132
  }
package/index.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
1
+ import { VERSION, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { supportsImageModels } from "./extensions/images/models.ts";
2
3
  import { registerPrompts } from "./extensions/prompts.ts";
3
4
  import { readTsgwSettings } from "./extensions/provider/config.ts";
4
5
  import { registerTsgwProvider } from "./extensions/provider/index.ts";
@@ -7,6 +8,10 @@ import { registerUploadTool } from "./extensions/upload/index.ts";
7
8
  /** 插件总入口:保持能力注册顺序,实现由各模块维护。 */
8
9
  export default async function registerTsgw(pi: ExtensionAPI): Promise<void> {
9
10
  registerUploadTool(pi);
11
+ if (supportsImageModels(VERSION)) {
12
+ const { registerImageTools } = await import("./extensions/images/tools.ts");
13
+ registerImageTools(pi);
14
+ }
10
15
  registerPrompts(pi);
11
16
  const settings = readTsgwSettings();
12
17
  await registerTsgwProvider(pi, settings);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-tsgw",
3
- "version": "0.3.0",
4
- "description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护聊天与图片模型目录及思考策略,支持四种聊天协议与原生图片生成。",
3
+ "version": "0.4.1",
4
+ "description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护聊天与图片模型目录及思考策略,支持四种聊天协议与图片生成、编辑工具。",
5
5
  "type": "module",
6
6
  "keywords": [
7
7
  "pi",
@@ -24,7 +24,7 @@
24
24
  ]
25
25
  },
26
26
  "scripts": {
27
- "test": "tsc -p tsconfig.test.json && node dist/extensions/provider/index.test.js && node dist/extensions/prompts.test.js && node dist/extensions/provider/status.test.js && node dist/extensions/search/index.test.js && node dist/extensions/search/proxy.test.js && node dist/extensions/search/host-integration.test.js && node dist/extensions/provider/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/extensions/images/models.test.js && node dist/extensions/images/adapter.test.js && node dist/extensions/images/host-integration.test.js && node dist/index.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
27
+ "test": "tsc -p tsconfig.test.json && node dist/extensions/provider/index.test.js && node dist/extensions/prompts.test.js && node dist/extensions/provider/status.test.js && node dist/extensions/search/index.test.js && node dist/extensions/search/proxy.test.js && node dist/extensions/search/host-integration.test.js && node dist/extensions/provider/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/extensions/images/models.test.js && node dist/extensions/images/parameters.test.js && node dist/extensions/images/input-budget.test.js && node dist/extensions/images/edit-request.test.js && node dist/extensions/images/image-data.test.js && node dist/extensions/images/response.test.js && node dist/extensions/images/stream-response.test.js && node dist/extensions/images/adapter.test.js && node dist/extensions/images/tool-files.test.js && node dist/extensions/images/tools.test.js && node dist/extensions/images/host-integration.test.js && node dist/extensions/images/tools-host.test.js && node dist/index.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
28
28
  "test:upload:live": "tsc -p tsconfig.test.json && node dist/extensions/upload/live.test.js"
29
29
  },
30
30
  "peerDependencies": {
@@ -44,7 +44,8 @@ compatibility: 需要宿主提供子代理工具及可用的 tsgw 模型。
44
44
 
45
45
  - **MiniMax-M3** 只承担步骤明确的小任务。参考使用 Pi 的 high;非 off 档位均映射为 adaptive,不代表不同能力档。adaptive 不是 Pi 档位,此映射不适用于 M3.1 Flash Preview。
46
46
  - **deepseek-flash** 作为按量付费补位时使用 max。
47
- - **Kimi** 不承担长程执行;双模型复核固定为 **Kimi+Astra**,独立审查同一份材料。Kimi 使用 kimi-k3 / high,Astra 深度按任务选择。
48
- - 用户明确要求、预算、权限及宿主实际能力优先;不可用的模型或档位如实说明。
47
+ - **Astra 审阅档位**:架构设计、正式设计文档的独立审阅与最终复核,默认使用 `gpt-6-astra` / `max`,不因材料篇幅短或范围明确而自动降档。局部检查、定向复审可按范围降低档位。
48
+ - **Kimi** 不承担长程执行;双模型复核固定为 **Kimi+Astra**,独立审查同一份材料。Kimi 使用 kimi-k3 / high,Astra 遵循上述审阅档位规则;其他任务的深度按任务选择。
49
+ - 不可用的模型或档位如实说明。
49
50
 
50
51
  宿主支持 `Agent.model = provider/modelId:level` 时,例如 `tsgw/MiniMax-M3:high`、`tsgw/glm-5.3:max`;其他宿主使用其实际格式。
@@ -0,0 +1,150 @@
1
+ ---
2
+ name: tsgw-image-generation
3
+ description: 当用户要求生成图片、生图或画图,以及修改图片、参考图创作或蒙版编辑时使用。通过 Code Mode 调用 tsgw_generate_image 或 tsgw_edit_image,根据草稿或成稿选择模型与参数,再按用户意图保存、发送、展示或继续编辑。
4
+ license: MIT
5
+ compatibility: 需要 Pi 1.2+、Code Mode、pi-tsgw 图片工具及可用的 tsgw 图片模型。
6
+ ---
7
+
8
+ # 图片生成与编辑
9
+
10
+ ## 选择工具和模型
11
+
12
+ - 从文字创建图片:在 Code Mode 中调用 `tools.tsgw_generate_image()`,填写 `prompt`。
13
+ - 根据一张或多张图片修改、参考创作:在 Code Mode 中调用 `tools.tsgw_edit_image()`,填写 `prompt` 和 `images`;局部修改可增加 `mask`。
14
+ - **草稿、构图探索、速度优先**:选择 `gpt-image-2.5-flare`,质量可用 `low`。
15
+ - **正式成图、精细修改、质量优先**:选择 `gpt-image-2.5-sunburst`,这是工具的默认模型;质量按需求从 `auto` 或 `high` 起选。
16
+
17
+ 按用户任务选择模型和参数。`prompt` 写清主体、构图、风格、尺寸意图,以及需要呈现或保留的文字与细节;编辑时区分“修改什么”和“保留什么”。
18
+
19
+ ## 通过 Code Mode 调用
20
+
21
+ 生成和编辑统一通过 `codemode` 执行 `tools.tsgw_generate_image()` 或 `tools.tsgw_edit_image()`,不要直接发起图片工具调用。检查状态和返回文件后,**按用户意图处理图片,不强制预览或展示**。Code Mode 不可用时说明调用条件不足,不改用直接调用或擅自修改配置。
22
+
23
+ 已实测的路径是 Code Mode 生成后读图并展示;该验证未覆盖编辑或直接调用。这里规定的是技能调用方式,不代表直接调用必然失败,也不代表此前未发出调用的底层原因已修复。
24
+
25
+ - 读取技能或说“现在生成”不算执行。收到生成任务后,应实际调用工具并检查结果;没有工具结果,不得声称已生成。
26
+ - 图片工具有 `outputSchema`,Code Mode 内嵌调用返回结构化状态和文件列表。保存、发送或继续编辑可以直接使用返回文件,无需先 `read` 或 `image()`;需要在对话中展示时,才读取文件并显式执行 `image(block)`。`text(result)` 仅报告状态和路径,不等于展示、发送或最终存储已完成;不要打印图片 base64。
27
+ - 工具本身直接调用时会返回图片块,但本技能使用 Code Mode 的结构化返回与文件处理流程;不要把内嵌调用等同于已向对话输出图片。
28
+
29
+ 完整生成示例(一次请求,默认 Sunburst):默认只返回文件;**任务需要在对话中展示时,将 `display` 改为 `true`**。若已有生成结果,只处理已有文件,不要重新运行生图调用。
30
+
31
+ ```js
32
+ // @options: {"timeout_ms": 660000, "max_output_tokens": 2000}
33
+ const display = false; // 按用户意图设置;仅需要在对话中展示时改为 true。
34
+ let result;
35
+ try {
36
+ result = await tools.tsgw_generate_image({
37
+ prompt: "横版中国水墨山水画,远山、薄雾、一叶扁舟,不要文字、题款、印章或水印。",
38
+ size: "1536x1024"
39
+ });
40
+ } catch {
41
+ text({ error: "图片调用未正常返回;请检查已有工具结果。上游是否已处理或计费可能未知,不自动重试或换模型。" });
42
+ return;
43
+ }
44
+ text(result);
45
+
46
+ if (result?.requestStatus !== "succeeded" || result.phase !== "complete") {
47
+ text({ error: result?.requestStatus === "succeeded"
48
+ ? "上游已成功,但结果处理或保存未完成;不要重新生成。"
49
+ : "未确认生成完成;按工具结果说明状态,不自动重试。" });
50
+ return;
51
+ }
52
+ if (!Array.isArray(result.files) || result.files.length === 0) {
53
+ text({ error: "工具报告完成但没有返回文件,无法继续交付;不要重新生成。" });
54
+ return;
55
+ }
56
+
57
+ if (!display) return; // 返回文件可用于保存、发送或继续编辑,不必读图预览。
58
+ let displayed = 0;
59
+ for (const file of result.files) {
60
+ try {
61
+ const block = await tools.read({ path: file.path });
62
+ if (block && typeof block === "object" && block.type === "image") {
63
+ image(block);
64
+ displayed++;
65
+ } else {
66
+ text({ error: "文件已生成,但未能读取为图片", path: file.path });
67
+ }
68
+ } catch {
69
+ text({ error: "文件已生成,但读取或展示失败;保留此路径,不要重新生成", path: file.path });
70
+ }
71
+ }
72
+ text({ generated: true, imagesEmitted: displayed, fileCount: result.files.length });
73
+ ```
74
+
75
+ ### 按意图处理返回文件
76
+
77
+ | 用户意图 | 后续操作 |
78
+ | --- | --- |
79
+ | 展示图片 | 对返回文件执行 `tools.read()`,再 `image(block)`;`imagesEmitted` 只统计已输出的图片块 |
80
+ | 保存图片 | 使用原始文件保存到用户要求的位置;工具返回的是临时路径,不等于已完成指定位置的持久保存 |
81
+ | 发送或上传 | 将文件交给相应的可用工具,在已有授权范围内执行;依据发送或上传结果确认完成 |
82
+ | 继续编辑 | 将原始文件路径用于下一次 `images[].path`,不必先读取预览 |
83
+
84
+ 后续读取、展示、保存或发送失败,与图片生成失败分开报告;保留已生成文件,只处理失败的后续步骤,不重新生图。
85
+
86
+ ## Code Mode 参数示例
87
+
88
+ 以下是传给 Code Mode 中相应 `tools.*` 调用的参数,不是直接工具调用指令,也不要逐个执行。
89
+
90
+ `tools.tsgw_generate_image()` 的最简参数:
91
+
92
+ ```json
93
+ {
94
+ "prompt": "横版水墨山水,远山薄雾,一叶扁舟,不要文字"
95
+ }
96
+ ```
97
+
98
+ 快速草稿:
99
+
100
+ ```json
101
+ {
102
+ "prompt": "极简咖啡馆标志草稿,咖啡杯与山峰结合,无文字",
103
+ "model": "gpt-image-2.5-flare",
104
+ "quality": "low",
105
+ "size": "1024x1024"
106
+ }
107
+ ```
108
+
109
+ 在上述 Code Mode 脚本中,将生成调用替换为 `tools.tsgw_edit_image()` 并传入以下参数即可编辑本地图片;蒙版对应第一张原图。沿用状态检查,再按用户意图处理返回文件;仅需展示时使用读图和 `image(block)` 步骤。**这是编辑契约示例,本次 Code Mode 实测未覆盖编辑。**
110
+
111
+ ```json
112
+ {
113
+ "prompt": "把蒙版标出的区域改为盛开的荷花,保留原图其余构图和水墨风格",
114
+ "images": [{ "path": "source.png" }],
115
+ "mask": { "path": "mask.png" }
116
+ }
117
+ ```
118
+
119
+ `images` 保留参考图顺序,支持 1–16 张;每个来源选择 `path`、`image_url`、`file_id` 其中之一。`path` 是 Pi 运行主机上的文件路径,相对路径以会话工作目录为准;`image_url` 接受 HTTP(S) URL 或图片 data URI,`file_id` 使用上游已有文件 ID。蒙版可省略;提供时,与第一张原图保持格式及尺寸一致,并带透明通道,用透明区域指示编辑范围。
120
+
121
+ ## 可选参数
122
+
123
+ 生成和编辑共用下列可选参数,省略时使用默认值;只填写任务需要覆盖的项。
124
+
125
+ | 参数 | 默认值 | 用途与取值 |
126
+ | --- | --- | --- |
127
+ | `model` | `gpt-image-2.5-sunburst` | 草稿用 Flare,正式成图用 Sunburst |
128
+ | `quality` | `auto` | `low`、`medium`、`high`、`xhigh`、`max`、`auto`;`xhigh`/`max` 用于确实需要额外细节的任务 |
129
+ | `size` | `auto` | `宽x高`;例如 `1024x1024`、`1536x1024`、`1024x1536`、`2048x1152`、`3840x2160` |
130
+ | `background` | `auto` | `auto`、`opaque`、`transparent`;透明输出搭配 PNG 或 WebP |
131
+ | `output_format` | `png` | `png`、`jpeg`、`webp` |
132
+ | `output_compression` | JPEG/WebP 使用 `100` | `0–100` 整数,用于 JPEG/WebP |
133
+ | `n` | `1` | 一次请求生成 `1–10` 张图片 |
134
+ | `moderation` | `auto` | `auto` 或 `low` |
135
+ | `stream` | `false` | 是否使用上游流式响应;工具处理完成后返回最终图片 |
136
+ | `partial_images` | `0` | 流式请求中希望收到的过程图数量,`0–3` |
137
+ | `safety_identifier` | 省略 | 应用需要时提供稳定的匿名用户标识,最多 128 字符 |
138
+ | `user` | 省略 | 上游旧用户标识字段;新接入使用 `safety_identifier` |
139
+ | `timeout_ms` | `600000` | 单次调用等待时间,单位毫秒;可按任务覆盖。通过 codemode 包装调用时,脚本截止应留余量,例如默认请求配 `660000` |
140
+
141
+ 自定义尺寸:宽高都是 16 的倍数,单边至多 3840,长短边比例至多 3,总像素为 655360–8294400;超过 3686400 像素属于上游实验范围。
142
+
143
+ ## 超时、安全与结果
144
+
145
+ - 生成可能耗时数分钟。工具请求默认 `600000ms`;Code Mode 示例用 `660000ms` 为调用、读图和输出留余量。延长请求的 `timeout_ms` 时,脚本截止也要相应留余量;脚本超时可能无法进入示例的 catch,仍应核对已有结果而不是再次生图。
146
+ - 请求失败、取消或超时不代表上游未处理或未计费;不自动重试或换模型。费用显示为 0 表示尚未映射准确价格,不表示免费。
147
+ - `requestStatus: succeeded`、`phase: complete` 和返回文件是生成完成的依据。生成成功不代表展示、发送或指定位置的保存也成功;只有任务要求的后续操作实际完成,才能作相应声明。没有展示要求时,不把未展示视为失败。
148
+ - 实际格式及尺寸以工具返回的 `files[].mimeType/width/height` 为准,不把请求的 `size` 直接当作最终尺寸。`read` 预览可能缩放或转码;继续编辑时使用原始文件的 `images[].path`,不要把预览当作原图。
149
+ - 本地/内联图片每个小于 50 MB,参考图与蒙版合计不超过 100 MB。原文件读取和外传由图片工具及宿主权限控制,不等于内置 `read` 的审批或沙箱;不绕过宿主对读图或工具的限制。
150
+ - 若结果带 `usage_note`,按其说明报告计量状态;多图流式的逐事件用量可能无法确定汇总值。