开发者 API

图片上传 API 使用文档

从服务端应用上传一张或多张图片，并查询管理员为 API 用户分配的已使用量和剩余量。

申请方式与长期存储相同，请发送邮件申请。管理员会向你提供 API 用户 ID 和 API Key。

[email protected]

基础地址https://api.mini-tools.uk

上传接口POST /v1/upload

已使用量和剩余量GET /v1/usage

上传记录GET /v1/images

删除图片DELETE /v1/images/:key

鉴权方式

每次请求都必须在请求头中同时发送管理员分配的用户 ID 和与其匹配的 API Key。

X-API-User-ID: assigned-user-id
Authorization: Bearer mtu_live_your_key

请只在可信服务端使用这两个凭证。用户 ID 用来识别账户，API Key 用来防止其他人冒用该账户。不要把 API Key 写入浏览器代码或公开仓库。

使用方法

向上传接口发送 multipart/form-data。单张上传使用一次 file 字段，批量上传则重复使用该字段。

上传单张图片

cURL

curl "https://api.mini-tools.uk/v1/upload" \
  -H "X-API-User-ID: assigned-user-id" \
  -H "Authorization: Bearer mtu_live_your_key" \
  -F "duration=7-day" \
  -F "file=@image.png"

上传多张图片

cURL

curl "https://api.mini-tools.uk/v1/upload" \
  -H "X-API-User-ID: assigned-user-id" \
  -H "Authorization: Bearer mtu_live_your_key" \
  -F "duration=7-day" \
  -F "file=@first.png" \
  -F "file=@second.webp"

安全重试

对于可能重试的上传，请发送唯一的 Idempotency-Key 请求头。使用相同 Key 重复提交相同请求时，会直接返回首次结果，不会重复上传或重复扣减额度；同一 Key 改传其他文件会返回 HTTP 409。

HTTP

Idempotency-Key: upload-request-001

请求字段

字段	必填	说明
`file`	是	一张图片，或重复相同字段上传多张图片。
`duration`	否	可选 1-day、7-day、30-day 或 permanent，分配的账户必须具有对应保留类型权限。

上传返回

全部上传成功返回 HTTP 201；批量上传中同时存在成功和失败时返回 HTTP 207，并分别列出结果。

JSON

{
  "success": true,
  "partial": false,
  "uploaded": [
    {
      "success": true,
      "key": "7-day/example.png",
      "url": "https://pub.mini-tools.uk/7-day/example.png",
      "duration": "7-day",
      "expires_at": "2026-08-05T12:00:00.000Z",
      "size": 24831,
      "mime": "image/png",
      "risk": "normal"
    }
  ],
  "failed": [],
  "usage": {
    "user_id": "assigned-user-id",
    "plan_type": "custom",
    "temporary": {
      "enabled": true,
      "limit": 100,
      "used": 1,
      "remaining": 99,
      "reset_at": "2026-08-05T16:00:00.000Z",
      "timezone": "Asia/Shanghai"
    },
    "permanent": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    },
    "usage_date": "2026-08-05"
  }
}

返回参数

字段	说明
`success`	仅当全部图片成功时为 true。
`partial`	批量上传部分成功、部分失败时为 true。
`uploaded`	成功图片数组，包含存储键、公开 URL、保留期、过期时间、大小、MIME 类型和审核风险状态。
`failed`	失败图片数组，包含从 0 开始的序号、文件名、错误说明和稳定错误码。
`account`	兼容使用的扁平额度对象。
`usage`	当前限时图与永久图的总量、已使用量和剩余量。

获取已使用量和剩余量

可在上传前后调用用量接口读取当前额度，查询本身不会消耗上传额度。

cURL

curl "https://api.mini-tools.uk/v1/usage" \
  -H "X-API-User-ID: assigned-user-id" \
  -H "Authorization: Bearer mtu_live_your_key"

JSON

{
  "success": true,
  "usage": {
    "user_id": "assigned-user-id",
    "plan_type": "custom",
    "temporary": {
      "enabled": true,
      "limit": 100,
      "used": 24,
      "remaining": 76,
      "reset_at": "2026-08-05T16:00:00.000Z",
      "timezone": "Asia/Shanghai"
    },
    "permanent": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    },
    "usage_date": "2026-08-05"
  }
}

查询上传记录

只返回当前 API 用户仍有效的上传记录，每个公开 URL 都可以直接使用。接口不会返回保留期、过期时间和审核状态。

cURL

curl "https://api.mini-tools.uk/v1/images?limit=20" \
  -H "X-API-User-ID: assigned-user-id" \
  -H "Authorization: Bearer mtu_live_your_key"

JSON

{
  "success": true,
  "records": [
    {
      "key": "7-day/example.png",
      "url": "https://pub.mini-tools.uk/7-day/example.png",
      "size": 24831,
      "mime": "image/png",
      "uploaded_at": "2026-08-05T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

limit 默认是 20，最大为 100。next_cursor 不为 null 时，将它作为 cursor 查询参数即可获取下一页。

删除已上传图片

删除当前鉴权 API 用户上传的图片，不能删除其他 API 用户的图片。删除图片不会返还每日额度或永久额度。

cURL

curl -X DELETE "https://api.mini-tools.uk/v1/images/7-day/example.png" \
  -H "X-API-User-ID: assigned-user-id" \
  -H "Authorization: Bearer mtu_live_your_key"

JSON

{
  "success": true,
  "deleted": {
    "key": "7-day/example.png",
    "url": "https://pub.mini-tools.uk/7-day/example.png"
  }
}

约束条件

支持格式：JPG、PNG、GIF 和 WebP。
每张图片最大 5 MB。
每次最多 10 张，所有图片合计不超过 25 MB。
保留期可选 1-day、7-day、30-day 和 permanent，具体取决于分配给账户的权限。
只有成功图片会占用额度。限时图每日额度按 Asia/Shanghai 时区零点重置；永久图使用总额度。
对可能重试的上传使用唯一 Idempotency-Key，避免重复图片和重复扣减额度。
管理员核验申请邮箱后才会启用 API 凭证；通过邮箱认证的 API 上传仍然需要遵守内容审核规则。
API 上传和网页上传遵守相同规则，违法、有害、私密或侵权图片可能被拒绝或删除。

HTTP 状态码

200 查询或删除成功。
201 全部图片上传成功。
207 批量上传部分成功。
400 / 413 / 415 请求格式、数量、大小或图片内容无效。
401 / 403 凭证无效、账户已停用或不允许该保留类型。
404 图片不存在或不属于当前 API 用户。
409 Idempotency-Key 正在处理中，或已被用于不同的上传请求。
429 每日额度或永久总额度已经用完。
503 API 数据库暂时不可用。

使用场景

在部署或测试流程中上传应用截图。
通过一次服务端请求批量上传商品图或文档图片。
在自动批量任务开始前检查剩余额度。

常见问题

一次请求可以上传多张图片吗？

可以。每张图片重复使用 file 字段，但不能超过文档中的张数和总大小限制。

只使用用户 ID 可以鉴权吗？

不可以。必须同时发送分配的用户 ID 和匹配的 API Key。ID 识别账户，Key 证明调用方有权使用该账户。

怎样知道还剩多少额度？

调用 GET /v1/usage，或者读取上传返回中的 usage 对象。

鉴权方式

使用方法

上传单张图片

上传多张图片

安全重试

请求字段

上传返回

返回参数

获取已使用量和剩余量

查询上传记录

删除已上传图片

约束条件

HTTP 状态码

使用场景

相关工具

常见问题