同步 Raw 图片代理契约

记录文本字段 16KiB 流式限制。记录 GPT-Image-2 固定 b64_json 响应格式。
2026-09-11 17:37:58 +08:00
parent 842d080a75
commit 0cebc39b6a
1 changed files with 4 additions and 3 deletions
@@ -27,7 +27,7 @@ width: 1536
 height: 1024
 ```

-`image` 和 `mask` 必须是 `image/png` 文件字段；服务端不信任客户端文件名，转发时使用固定文件名。空文件、非 PNG 字节、MIME 不匹配或 mask 与 image 尺寸不一致均在扣费前返回 400。`prompt` 必填，UTF-8 原始字节长度不得超过 `4 KiB`；超限在扣费前返回 400。`quality`、`background` 和 `output_format` 采用 GPT Image 模型支持的值。字段不能重复，未知字段拒绝；缺失的必填字段拒绝。
+`image` 和 `mask` 必须是 `image/png` 文件字段；服务端不信任客户端文件名，转发时使用固定文件名。空文件、非 PNG 字节、MIME 不匹配或 mask 与 image 尺寸不一致均在扣费前返回 400。`prompt` 必填，UTF-8 原始字节长度不得超过 `16 KiB`；其它文本字段也使用同一 `16 KiB` 有界流式读取，超限在扣费前返回 400。`quality`、`background` 和 `output_format` 采用 GPT Image 模型支持的值。字段不能重复，未知字段拒绝；缺失的必填字段拒绝。

 `width`、`height` 使用严格输出尺寸规则，均在扣费前校验：

@@ -38,13 +38,14 @@ height: 1024

 校验通过后按整数尺寸发送给 provider，不静默 clamp 或改写调用者尺寸。

-Raw 路由的 multipart body limit 为 `64 MiB`，覆盖图片和文本字段；文件字段由 multipart 解析器直接收集为字节，随后在阻塞线程中完成 PNG 解码。PNG 解码使用与输出合同一致的资源上限：宽高各不超过 `3840`，解码分配不超过 `8294400 × 4` 字节；不再执行 base64 入站解码。
+Raw 路由的 multipart body limit 为 `64 MiB`，覆盖图片和文本字段；图片字段由 multipart 解析器收集为可共享字节缓冲，文本字段按 chunk 流式读取并在达到 `16 KiB` 时立即拒绝，随后在阻塞线程中完成 PNG 解码。PNG 解码使用与输出合同一致的资源上限：宽高各不超过 `3840`，解码分配不超过 `8294400 × 4` 字节；不再执行 base64 入站解码。

 服务端发送给 `platform-image` 时固定注入：

 ```text
 model = gpt-image-2
 n = 1
+response_format = b64_json
 ```

 请求不暴露 `model`、`n`、`response_format`、`style`、`user` 或 `output_compression`。
@@ -85,7 +86,7 @@ raw 操作使用独立的 operation / ledger 命名空间，例如 `raw-image-ed

 `platform-image` 保留 VectorEngine 协议细节。raw handler 只负责：认证、multipart 字段解析、PNG 预检查、计费编排和响应映射。provider 请求仍由 `platform-image` 统一构造，并携带 `model`、`n`、`quality`、`background`、`output_format`、尺寸及图片参考字节。

-provider 响应只提取并透传 `data[].b64_json` 字符串，不在服务端解码图片 base64，也不读取或回传 provider 的 `output_format`（该字段只是请求参数回显）。发送、响应读取、上游状态、响应解析和缺图失败必须生成 `PlatformImageFailureAudit`，由 api-server 写入现有外部 API 失败审计链；成功结果同时写入统一的 `external_generation_run` 追踪事件。raw handler 只将上游 `b64_json` 原样写入 `data[].b64_json`。
+provider 响应只提取并透传 `data[].b64_json` 字符串，不在服务端解码图片 base64，也不读取或回传 provider 的 `output_format`（该字段只是请求参数回显）。GPT-Image-2 的 provider 请求显式固定 `response_format=b64_json`，因此不实现 URL 响应下载或兼容分支。发送、响应读取、上游状态、响应解析和缺图失败必须生成 `PlatformImageFailureAudit`，由 api-server 写入现有外部 API 失败审计链；成功结果同时写入统一的 `external_generation_run` 追踪事件。raw handler 只将上游 `b64_json` 原样写入 `data[].b64_json`。

 ## 代码拆分