# 图片

每个图片输入都是一个对象，且以下三个成员中只能有一个。

| 成员 | 值 |
|---|---|
| `id` | `POST /v1/images` 返回的句柄，格式为 `img_<sha256>`。 |
| `base64` | JPEG、PNG 或 WebP 文件的标准 base64。允许带 `data:` 前缀。 |
| `url` | 预留。`https://` 链接暂不支持，会返回 `400 unsupported`。 |

```json
{ "image": { "base64": "/9j/4AAQSkZJRgABAQ..." } }
```

```json
{ "image": { "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2" } }
```

## 上传与复用

`POST /v1/images` 保存图片并返回句柄，不收费。句柄可避免重复发送相同的字节，例如多个提示、多次修整或多个模型处理同一张图片时。

文件可以用 `multipart/form-data`（字段名 `file`）发送，也可以作为原始请求体发送，并将 `Content-Type` 设为 `image/jpeg`、`image/png` 或 `image/webp`。

```bash
curl https://api.stack.foldbun.com/v1/images \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg
```

```json
{
  "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2",
  "width": 1343,
  "height": 1008,
  "bytes": 388375,
  "contentType": "image/jpeg"
}
```

句柄按内容寻址：重复上传同一张图片会返回相同的 `id`，状态码为 200 而不是 201。`width` 和 `height` 是摆正后的原图（已应用 EXIF 方向）的尺寸，也是之后所有调用的坐标空间。

句柄只在上传它的账户内有效，其他账户的句柄无法解析。

### 保留策略

图片本身按尽力而为的方式保留，最长保留 7 天，从账户首次存储该图片时起算，到期后删除。存储容量不足时，Stack 还会更早淘汰最久未使用的图片，因此不设最短保留期限。调用返回 `404 image_not_found` 时，应重新上传图片并重复调用。

图片存储暂时不可用时，调用返回可重试的 `503 unavailable`，并带有 `Retry-After`。

## 接受的输入

| 属性 | 限制 |
|---|---|
| 格式 | JPEG、PNG、静态 WebP |
| 文件大小 | 每次上传最大 20 MiB |
| 像素 | 最多 40 百万像素，每边最多 16384 px |
| JSON 请求体 | 最大 28 MiB，以容纳 base64 图片 |

文件或请求体超过大小限制时，返回 `413 payload_too_large`。不受支持或格式错误的文件，以及超出像素限制的图片，返回 `400 invalid_request`。通过这些检查但无法解码的文件，在模型首次需要它时返回 `400 invalid_image`，同一句柄之后始终返回 `400 invalid_image`。此类调用不收费。图片处理繁忙时，返回可重试的 `503 unavailable`。

以 `base64` 内嵌的图片与上传的处理方式相同。

## 存储与隐私

上传的图片在到达时即被清理：元数据（EXIF、XMP、注释、内嵌缩略图）和附加在图片之后的数据会被删除。像素不会被修改或重新编码，因此 JPEG 仍是 JPEG，PNG 仍是 PNG，WebP 仍是 WebP。

图片本身最长保留 7 天（见[保留策略](#保留策略)）。图片不会转发给 GPU 节点，节点只收到 Stack 按模型生成的缩放副本。

`img_<sha256>` 是清理后字节的 SHA-256，而不是上传文件的 SHA-256。

## 坐标

请求和响应中的所有坐标，均为摆正后的原图的像素坐标：即应用 EXIF 方向后、保持完整尺寸的上传图片。这包括框（`[x1, y1, x2, y2]`）、点、多边形和四边形。尺寸在每个带图片的响应中以 `image.width` 和 `image.height` 返回，`POST /v1/images` 也会返回。不做缩放，也没有短边限制：限制见[接受的输入](#接受的输入)，最多 40 百万像素，每边最多 16384 px。

上传前缩小图片的，坐标基于缩小后的像素。较小的上传可节省上传时间和带宽；模型在任何情况下都使用缩放后的副本。

## 蒙版

`bbox` 和 `polygon` 始终使用图片像素。蒙版只在请求时返回（`geometry: ["mask"]`），可以比图片小。蒙版的 `mask.size`（`[高, 宽]`）是蒙版网格的实际尺寸，客户端按它缩放：x 乘以 `image.width / size[1]`，y 乘以 `image.height / size[0]`。详见[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。

`POST /v1/segment` 和 `POST /v1/refine` 的 `options.maskSize` 设置返回蒙版网格的长边，范围 64 到 4096 px，默认 2048。网格不会比图片大。该选项只影响 `mask` 输出；多边形按图片分辨率描绘。数值超出范围，返回 `400 invalid_request`。