# 更新日志

## 2026-11-04 — 分割后处理、多边形输出、CBOR 响应

**API（不兼容变更）**

- 分割结果（`POST /v1/segment`、`POST /v1/refine`、批量分割）默认返回含洞的简化多边形，不返回蒙版。`Instance.polygon` 为部分列表 `{outer, holes}`，环为图片像素的扁平整数数组。`bbox` 为整数，x2 和 y2 不包含在内；每个实例都带有 `area`。
- 蒙版按需返回（`geometry: ["mask"]`），放在 `mask` 中：COCO 压缩 RLE（`encoding: coco`，默认）或无损 WebP 裁剪区域（`encoding: webp`）。未压缩的整数 `rle` 已删除。
- 后处理按提示配置（`prompts[].options`），叠加在请求级默认值（`options.defaults`）之上：分数、尺寸和面积过滤（含贴边模式，默认 `strict`）、碎片与洞的清理、多边形容差、洞与部分数量，以及按 `group` 合并。请求级新增 `options.maxInstances`、`options.nms` 和 `options.report`。响应返回 `dropStats`，按需返回 `dropped`。
- 已删除：`options.threshold`（改为 `filter.minScore`）、`options.maxDetections`（改为 `options.maxInstances`）、`options.polygons`（多边形为默认输出）。取消 `maskSize` 大于 2048 时最多 10 个提示的限制。
- 取决于图片内容的限制（每个实例的顶点数、每个响应的几何数据量、WebP 像素）按文档规则缩减输出（`tolerancePx`、`omitted`、`mask.encoding`），不会使调用失败。
- `Accept: application/cbor` 以 CBOR 返回分割、修整、背景移除和 JSON 模式批量的响应：多边形环为 RFC 8746 类型化数组，二进制数据为字节串。

## 2026-11-02 — 原图尺寸坐标、蒙版尺寸、图片存储

**API**

- 请求和响应中的坐标均为摆正后的原图（已应用 EXIF 方向）的像素坐标。图片不再缩小到短边 1008 px；`image.width` 和 `image.height` 是原图的尺寸，最多 40 百万像素，每边最多 16384 px。
- 蒙版可以比图片小。`rle.size` 是蒙版的实际尺寸，客户端按它缩放。
- `POST /v1/segment` 和 `POST /v1/refine` 新增 `options.maskSize`：返回蒙版的长边，范围 64 到 4096 px，默认 2048。大于 2048 时，`POST /v1/segment` 最多接受 10 个提示。
- 新增错误 `400 invalid_image`：图片通过了上传检查，但无法解码。此类调用不收费。
- 带有 `Retry-After` 的 `503 unavailable` 也可能表示图片存储暂时不可用。

**隐私**

- 元数据和附加数据在上传时删除。图片本身最长保留 7 天。图片不会转发给 GPU 节点，节点只收到按模型生成的缩放副本。内嵌的 `base64` 图片与上传的处理方式相同。

## 2026-11-02 — 图片保留期限

- 图片句柄和缓存的编码最长保留 7 天，从账户首次存储该图片时起算，到期后删除。存储容量不足时仍可能更早被清除，因此不设最短保留期限。使用已删除的句柄调用会返回 `404 image_not_found`，应重新上传图片。

## 2026-11-01 — sam3 支持点提示，文档按用例组织

**API**

- `sam3` 在 `POST /v1/segment` 中接受点提示：`{ "point": { "x", "y" } }` 每个点恰好返回一个对象。点提示可以与文本提示和样例框在一次调用中混用，并计入 50 个提示的上限。`options.threshold` 和 `options.maxDetections` 只作用于文本提示和样例框的实例，样例框只作用于文本提示。
- 点提示按 `point` 计费，单价与 `sam3` 的点相同；图片编码每次调用计费一次。
- `POST /v1/refine` 按调用计费：每次调用计一个 `refine` 单位（`sam3` 0.02，`sam-lite` 0.01，一次解码），与点的数量以及是否带框无关。`POST /v1/segment` 中的样例框不再单独计费：每个文本提示计为一个 `prompt`，只含样例框而没有文本提示的调用计为一个 `prompt`。
- 未变：`sam3` 分割调用中的 `box` 为样例框。用框标出单个物体请使用 `POST /v1/refine`。

**文档**

- 新增六个用例页面：交互分割、概念分割、文字识别、文档解析、嵌入与检索、抠图。每个页面说明请求与响应，并比较适用于该任务的模型。
- 模型页面介绍模型本身、权重、许可证、工作原理、计费单位和限制，以及模型在各用例下的特性。
- 侧边栏以缩进显示层级。
- 用例页面先说明任务及其场景，再比较模型，最后给出一个调用示例及其费用。请求与响应字段的说明见 API 参考；模型页面不再重复计费单位，计费单位见计费页面。

## 2026-11 — 首次发布

公共 API 版本 `0.1.0-draft`。

**接口**

- `POST /v1/images`：上传图片并获得可复用的 `img_` 句柄。
- `POST /v1/segment` 和 `POST /v1/refine`：使用 `sam3` 和 `sam-lite` 进行分割。
- `POST /v1/ocr`：使用 `ppocr-v6` 进行文字识别。
- `POST /v1/documents/parse`：使用 `paddleocr-vl` 对单个页面进行版面分析与识别。
- `POST /v1/embeddings`：使用 `dinov3` 和 `siglip2` 进行图像和文本嵌入。
- `POST /v1/remove-background`：使用 `birefnet` 移除背景。
- `GET /v1/models`：模型、价格和各账户的可用性。

**平台**

- 带模型范围、有效期和轮换的 API 密钥。
- 预付额度；1 额度 = US$0.001。每次调用返回 `cost`、`balance`、`billing` 和 `timing` 字段。
- 带每日额度的模型池：公共池和免费池，以及从余额中扣费的付费模型。
- 会消耗额度的调用支持 `Idempotency-Key`；每个响应都带有 `X-Request-Id`。
- Playground，其试用通道无需账户。

**暂未提供**

- 异步任务和 webhook。
- `image.url` 输入；图片以 base64 发送或先上传。
- `POST /v1/documents/parse` 的多页 PDF 输入。