API reference
Data plane
Uploads and URL fetch, authenticated with upload tokens
POST
multipart 表单上传。格式以 magic bytes 判定（jpeg / png / gif / webp），超过单图上限或像素预算即拒绝。
带 Idempotency-Key 头时，保留期内同一键重试返回同一张图。
bearerTokenheader
AuthorizationBearer <token>后台签发的具名上传 Token，仅授权数据面；管理后台不接受它。
Idempotency-Key?string客户端幂等键；保留期（运营配置 idempotency_key_ttl_hours）内同一用户同一键的重试返回同一张图
multipart/form-data- body
file*string图片文件；文件名作元数据展示
exif_policy?string本次 EXIF 档位；缺省用运营配置的全局默认
Value in
"strip""passthrough"ttl?string有效期秒数（0 到 3153600000 的整数）或 never 表示永久；缺省按「用户默认 > 全局默认」回退
已入库
application/json- response
id*string图片短 ID
url*string图片绝对访问地址；配置了 base_url 用配置，否则按请求推导
Format
uricurl -X POST 'http://localhost:8721/api/upload' \ -F 'file=string'{ "id": "string", "url": "http://example.com"}POST
服务端抓取远端图片后走与直传相同的管道；仅允许公网 http/https 地址，远端声明的类型不参与判定。
bearerTokenheader
AuthorizationBearer <token>后台签发的具名上传 Token，仅授权数据面；管理后台不接受它。
Idempotency-Key?string客户端幂等键；保留期（运营配置 idempotency_key_ttl_hours）内同一用户同一键的重试返回同一张图
application/json- body
url*string待转存的图片地址，仅 http / https 的公网地址
Format
urifile_name?string覆盖由地址末段推断的文件名
exif_policy?string本次 EXIF 档位；缺省用全局默认
Value in
"strip""passthrough"ttl?|有效期秒数（数字或数字字符串）或 never；缺省按「用户默认 > 全局默认」回退
已入库
application/json- response
id*string图片短 ID
url*string图片绝对访问地址；配置了 base_url 用配置，否则按请求推导
Format
uricurl -X POST 'http://localhost:8721/api/upload/url' \ -H 'Content-Type: application/json' \ -d '{ "url": "http://example.com"}'{ "id": "string", "url": "http://example.com"}