Documentación de la API de subida de imágenes

Autenticación

Ayuda con la solicitud y la recepción

• Escribe un mensaje breve, por ejemplo para solicitar la subida de imágenes de documentación por API. Solo un asunto, un adjunto o una firma automática no cuenta como solicitud. Los mensajes vacíos o ilegibles no reciben respuesta automática ni credenciales.
• Si no llega una respuesta, revisa el correo no deseado y confirma que enviaste texto legible. Evita repetir el mismo tipo de solicitud desde la misma dirección en 24 horas. Si la respuesta indica que falló la creación, requiere ayuda de soporte; no significa que la cuenta esté activa. Indica a [email protected] tu dirección de envío y la hora de solicitud, nunca tu API Key.
• Si tu correo ya tiene una cuenta API activa, volver a solicitarla no reenvía la clave original. Pide a soporte que la restablezca si la has perdido. Si la cuenta está desactivada, contacta con soporte; repetir subidas no la reactiva.
• Las cuentas nuevas creadas automáticamente por correo comienzan con 100 imágenes temporales al día y duración de 1-day, 7-day o 30-day. El almacenamiento permanente por API no está activado por defecto. Consulta GET /v1/usage antes de un lote para comprobar tus permisos actuales y la cuota restante.

Cada solicitud debe enviar el ID asignado y la API Key correspondiente en los encabezados.

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

Uso

Envía multipart/form-data. Usa file una vez para una imagen o repite el campo para un lote.

Subir una imagen

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"

Ejemplo de Node.js

Lee MTU_API_USER_ID y MTU_API_KEY del entorno, sube un archivo, comprueba el estado HTTP, analiza el éxito o el fallo y registra un resultado desensibilizado (url, duration, expires_at, usage). No incrustes secretos reales.

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

Subir varias imágenes

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"

Reintentos seguros

Para una subida que pueda repetirse, envía un Idempotency-Key único. La misma solicitud con la misma clave devuelve el primer resultado sin volver a subir ni consumir cuota dos veces. Usar la clave con otros archivos devuelve HTTP 409.

Idempotency-Key: upload-request-001

Campos de solicitud

Respuesta de subida

El éxito completo devuelve HTTP 201. HTTP 207 indica que unas imágenes se almacenaron y otras fallaron: revisa uploaded y failed aunque success sea false y conserva las URL correctas. Tras corregir los archivos fallidos, sube solo esos archivos con un nuevo Idempotency-Key. Repetir la solicitud original con su clave original devuelve el resultado original.

El JSON siguiente ilustra la estructura de respuesta. Sus URL, fechas y valores de cuenta son ejemplos, no una subida real ni una garantía de tu cuota.

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

Campos devueltos

Obtener cuota usada y restante

Llama al endpoint antes o después de subir. La consulta no consume cuota.

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

Consultar el historial de subidas

Devuelve solo las subidas activas del usuario API actual. Cada URL pública se puede usar directamente. No incluye duración, caducidad ni estado de revisión.

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 es 20 por defecto y 100 como máximo. Cuando next_cursor no sea null, envíalo como parámetro cursor para obtener la página siguiente.

Eliminar una imagen subida

Elimina una imagen del usuario API autenticado. No se pueden eliminar imágenes de otro usuario API. La eliminación no restaura la cuota diaria ni la permanente.

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

Limitaciones

• Formatos: JPG, PNG, GIF y WebP.
• Máximo 5 MB por imagen.
• Máximo 10 imágenes y 25 MB por solicitud.
• Duración: 1-day, 7-day, 30-day o permanent, según los permisos.
• Solo las imágenes correctas consumen cuota. La cuota temporal se reinicia a medianoche en Asia/Shanghai; la permanente es total.
• Usa un Idempotency-Key único en subidas que puedan repetirse para evitar imágenes duplicadas y doble consumo de cuota.
• Las credenciales del correo automático se pueden usar mientras la cuenta esté activa. Un administrador puede desactivar la cuenta después. Las subidas por API siguen sujetas a revisión de contenido.
• Las mismas reglas se aplican a la API y a la web. Las imágenes ilegales, dañinas, privadas o infractoras pueden eliminarse.

Códigos HTTP

• 200 Consulta o eliminación correcta.
• 201 Todas las imágenes se subieron.
• 207 Lote parcialmente correcto.
• 400 / 413 / 415 Solicitud, cantidad, tamaño o contenido no válido.
• 401 / 403 Credenciales no válidas, cuenta desactivada o tipo no permitido.
• 404 La imagen no existe o no pertenece al usuario API actual.
• 409 El Idempotency-Key se está procesando o se reutilizó para una subida diferente.
• 429 Cuota diaria o permanente agotada.
• 503 Base de datos API no disponible temporalmente.

Casos de uso

• Subir capturas desde procesos de despliegue o pruebas.
• Subir varias imágenes de producto o documentación.
• Comprobar la cuota antes de un lote automático.

Herramientas relacionadas

FAQ