图片

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

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

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

{ "image": { "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2" } }

上传与复用

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

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

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

{
  "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]。详见后处理。

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