注册存储
PUT /storages/{name} 以您自选的名称注册您的某个 S3 兼容存储（AWS S3、Cloudflare R2、Backblaze B2、
Wasabi、MinIO、DigitalOcean Spaces …），或替换您已有的同名存储。注册后，即可在请求中指定它，从中读取模板（source）并将文件保存到其中（Save）。
名称由小写字母、数字、- 和 _ 组成，最多 63 个字符。请求正文：
| 字段 | |
|---|---|
serviceUrl |
服务的端点：https://s3.eu-west-2.amazonaws.com、https://ACCOUNT.r2.cloudflarestorage.com … 必须使用 https，且位于公共互联网上。 |
region |
请求签名所用的区域：AWS 为存储桶所在区域，R2 为 auto，其他大多数服务为 us-east-1（默认值）。 |
bucket |
存储桶。 |
prefix |
存储桶中作为此存储的文件夹：键都位于其中，且无法访问其上级。未给出时：整个存储桶。 |
pathStyle |
路径样式寻址（endpoint/bucket/key），这是 AWS 以外的大多数服务所要求的方式。未给出时为 true。 |
accessKeyId、secretAccessKey |
密钥。请提供只能读写此存储桶或前缀的密钥。 |
示例
PUT /storages/main
X-API-KEY: your-api-key
Content-Type: application/json
{
"serviceUrl": "https://ACCOUNT.r2.cloudflarestorage.com",
"region": "auto",
"bucket": "my-bucket",
"prefix": "piq/",
"accessKeyId": "your-access-key-id",
"secretAccessKey": "your-secret-access-key"
}
新存储返回 201 Created，重新注册的存储返回 200：
{
"name": "main",
"serviceUrl": "https://ACCOUNT.r2.cloudflarestorage.com",
"region": "auto",
"bucket": "my-bucket",
"prefix": "piq/",
"pathStyle": true,
"accessKeyId": "…MPLE",
"createdAt": "2026-10-31T09:59:42.527Z",
"updatedAt": "2026-10-31T09:59:42.527Z"
}
存储在保存之前会先进行测试，即使用给定的密钥列出其内容。如果无法访问、不存在该存储桶或拒绝了密钥，则不会注册，并在响应（502，未及时响应则为 504）中说明原因。秘密访问密钥会加密保存，且绝不会返回；访问密钥 ID 只返回其最后四个字符。
一个许可证最多可以拥有 10 个存储：再注册一个会被拒绝（409）。