Image Upload API documentation

Authentication

Application and delivery help

• Write a short message in the email body, for example that you want to upload documentation images through the API. A subject alone, an attachment alone or an automatic signature does not count as a request. Empty or unreadable messages do not receive an automatic reply or credentials.
• If no reply arrives, check spam and confirm that your email included readable text. Avoid repeating the same type of application from the same address within 24 hours. A reply saying setup failed requires support follow-up; it is not an active account. Contact [email protected] with the sending address and application time, never your API key.
• If an active API account already exists for your email, applying again does not resend the original key. Ask support for a key reset if it is lost. If an account is disabled, contact support; repeated uploads will not reactivate it.
• New accounts created by email start with 100 temporary images per day and can select 1-day, 7-day or 30-day retention. Permanent API storage is not enabled by default. Read GET /v1/usage for your current permissions and remaining quota before a batch.

Every request must send the assigned user ID and the matching API key in request headers.

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

How to use

Send multipart/form-data to the upload endpoint. Use the file field once for a single image or repeat it for a batch.

Single image upload

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 example

Read MTU_API_USER_ID and MTU_API_KEY from the environment, upload a file, check the HTTP status, parse success or failure, and log a desensitised result (url, duration, expires_at, usage). Do not hard-code real secrets.

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,
  });
}

Multiple image upload

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"

Safe retries

For an upload that may be retried, send a unique Idempotency-Key header. Repeating the same request with the same key returns the first result without uploading again or consuming quota twice. Reusing the key for different files returns HTTP 409.

Idempotency-Key: upload-request-001

Request fields

Upload response

A complete success returns HTTP 201. HTTP 207 means some images were stored and others failed: inspect uploaded and failed even though success is false. Keep the successful URLs. After correcting the failed files, upload only those files with a new Idempotency-Key; replaying the original request with its original key returns the original result.

The JSON below illustrates the response structure. Its image URLs, dates and account values are examples, not a live upload record or a promise of your account allowance.

{
  "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"
  }
}

Returned fields

Get used and remaining quota

Call the usage endpoint before or after an upload to read the current allowance. It does not consume upload quota.

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

{
  "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"
  }
}

Get upload records

Returns only the current API user's active upload records. Each public URL can be used directly. Retention, expiry and review status are not included.

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"

{
  "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 defaults to 20 and is capped at 100. When next_cursor is not null, pass it as the cursor query parameter to request the next page.

Delete an uploaded image

Deletes an image uploaded by the authenticated API user. Images owned by another API user cannot be deleted. Deleting an image does not restore daily or permanent quota.

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"

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

Limitations and conditions

• Accepted formats: JPG, PNG, GIF and WebP.
• Maximum size: 5 MB per image.
• Maximum batch: 10 images and 25 MB total per request.
• Retention values: 1-day, 7-day, 30-day and permanent, subject to the assigned account permissions.
• Only successful images consume quota. Temporary quotas reset at midnight in Asia/Shanghai; permanent quotas are total allowances.
• Use a unique Idempotency-Key for retryable uploads to prevent duplicate images and duplicate quota use.
• API credentials from the automatic reply can be used while the account remains active. An administrator may disable an account later. API uploads remain subject to content review.
• The same upload rules apply to API and website uploads. Illegal, harmful, private or infringing images may be rejected or removed.

HTTP status codes

• 200 Query or deletion succeeded.
• 201 All images uploaded successfully.
• 207 A batch was partially successful.
• 400 / 413 / 415 The request, count, size or image content is invalid.
• 401 / 403 Credentials are invalid, the account is disabled or the retention type is not allowed.
• 404 The requested image does not exist or does not belong to the current API user.
• 409 The Idempotency-Key is already processing or was reused for a different upload.
• 429 The daily or permanent quota is exhausted.
• 503 The API database is temporarily unavailable.

Use cases

• Upload application screenshots from a deployment or testing workflow.
• Upload multiple product or documentation images in one server request.
• Check quota before starting an automated batch.

Related tools

FAQ