Image Upload API documentation

Authentication

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"

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. A batch with both successful and failed images returns HTTP 207 and lists each result separately.

{
  "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 are activated only after the administrator verifies the applicant's email address. 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 Usage query 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