开发者 API

图片上传 API 使用文档

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

请发送邮件到 [email protected]，并在正文中写明申请。新账户由系统尝试自动创建 API 用户 ID 和 API Key，再通过邮件回传。发出申请本身不代表凭证已成功送达。

基础地址https://api.mini-tools.uk
上传接口POST /v1/upload
已使用量和剩余量GET /v1/usage
上传记录GET /v1/images
删除图片DELETE /v1/images/:key

鉴权方式

申请与收信排查

  • 请在正文写一段简短申请，例如希望通过 API 上传文档配图。只有主题、只有附件或只有自动签名不算申请正文；空正文或无法读取正文的邮件不会收到自动回信或凭证。
  • 未收到回信时，请检查垃圾邮件，并确认申请含可读正文。同一邮箱、同一类型申请请勿在 24 小时内重复发送。若回信提示自动开户失败，需要联系支持处理，不能视为账户已启用。请向 [email protected] 提供发件邮箱和申请时间，不要发送 API Key。
  • 如果该邮箱已有启用的 API 账户，再次申请不会重新发送原 Key。Key 丢失时请联系支持重置。若账户已停用，请联系支持；反复上传不会重新启用账户。
  • 通过邮件自动创建的新账户默认每天可上传 100 张限时图片，可选 1-day、7-day 或 30-day；默认不开放 API 永久存储。批量上传前，请用 GET /v1/usage 核对账户当前权限与剩余额度。

每次请求都必须在请求头中同时发送管理员分配的用户 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"

Node.js 示例

从环境变量读取 MTU_API_USER_ID 和 MTU_API_KEY，上传文件，检查 HTTP 状态，解析成功或失败，并记录脱敏结果（url、duration、expires_at、usage）。请勿硬编码真实密钥。

Node.js
import fs from "node:fs";
import path from "node:path";

const userId = process.env.MTU_API_USER_ID;
const apiKey = process.env.MTU_API_KEY;

if (!userId || !apiKey) {
  throw new Error("Set MTU_API_USER_ID and MTU_API_KEY in the environment");
}

const form = new FormData();
form.append("duration", "7-day");
form.append(
  "file",
  new Blob([fs.readFileSync("./image.png")], { type: "image/png" }),
  path.basename("./image.png")
);

const response = await fetch("https://api.mini-tools.uk/v1/upload", {
  method: "POST",
  headers: {
    "X-API-User-ID": userId,
    Authorization: `Bearer ${apiKey}`,
  },
  body: form,
});

const payload = await response.json();

if (!response.ok || payload.success !== true) {
  console.error("Upload failed", {
    status: response.status,
    failed: payload.failed || null,
  });
  process.exitCode = 1;
} else {
  const item = payload.uploaded?.[0] || {};
  console.log({
    url: item.url,
    duration: item.duration,
    expires_at: item.expires_at,
    usage: payload.usage
      ? {
          temporary_used: payload.usage.temporary?.used,
          temporary_remaining: payload.usage.temporary?.remaining,
          permanent_used: payload.usage.permanent?.used,
          permanent_remaining: payload.usage.permanent?.remaining,
        }
      : null,
  });
}

上传多张图片

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 表示部分图片已存储、部分失败：即使 success 为 false，也要分别检查 uploaded 和 failed，并保存成功图片的 URL。修正失败文件后，只重传这些文件并使用新的 Idempotency-Key；用原 Key 重放原请求只会返回原结果。

下方 JSON 用于说明返回结构。图片 URL、日期和账户数值均为示例，不是真实上传记录，也不代表你的账户额度。

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 对象。