API de imgpile

Sube, comparte y gestiona imágenes y videos de forma programática.

https://imgpile.com/api/v1 — todos los endpoints

https://cdn.imgpile.com/api/v1/media — solo subidas de archivos (ver abajo)

Obtén un token de API

Iniciar sesión o regístrate para generar un token de API.

Conceptos

imgpile tiene dos objetos principales. Entender la diferencia te ahorrará tiempo.

Contenido multimedia

Un solo archivo (imagen o video). Tiene una URL directa de CDN, ideal para hotlinking, incrustar o compartir.

Publicación

Una página compartible que contiene uno o más elementos multimedia. Tiene título, descripción, votaciones, comentarios y etiquetas.

¿Solo necesitas una URL directa de imagen? Subir a /media. Usa urls.original de la respuesta. Listo.

¿Quieres una publicación compartible con comentarios y votaciones? Sube el contenido primero y luego llama a /posts con los IDs de los medios.

Inicio rápido

Sube un solo archivo y obtén una URL directa de CDN. Perfecto para ShareX, bots de Discord o cualquier script que solo necesite alojar una imagen.

Nota: las cargas van a cdn.imgpile.com, no imgpile.com.

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Respuesta:

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

Sube varios archivos y luego agrúpalos en una publicación con metadatos, votaciones y comentarios.

1. Sube cada archivo a cdn.imgpile.com y guarda el ID de medio devuelto:

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"
# Returns: { "media": { "id": 12345, ... } }

2. Crea una publicación con esos IDs:

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
# Returns: { "post": { "slug": "xyz789", ... } }

3. (Opcional) Agrega un título y una descripción:

curl -X PATCH https://imgpile.com/api/v1/posts/xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My post", "description": "Summer 2026"}'

Tu publicación ya está en vivo en https://imgpile.com/p/xyz789

Sube una imagen desde un navegador o Node.js:

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.imgpile.com/api/v1/media', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
    },
    body: formData,
});

const { media } = await response.json();
console.log(media.urls.original); // https://cdn.imgpile.com/f/abc1234.jpg

Configuración de ShareX

Descarga nuestra configuración de Custom Uploader e impórtala en ShareX; no necesitas editar JSON manualmente.

Descargar imgpile.sxcu

Haz clic en el botón de arriba para descargar imgpile.sxcu.
Haz doble clic en el archivo: ShareX lo importará y hará imgpile que haya un cargador disponible.
Abrir Destinations → Custom uploader settings → Headers y reemplaza YOUR_TOKEN_HERE por tu token de API (genera uno en el Introducción).
Configurar Destinations → Image uploader → imgpile. Captura una captura de pantalla: la URL se copiará en tu portapapeles como https://cdn.imgpile.com/f/….

Autenticación

Los endpoints de lectura (GET) son públicos y no requieren autenticación. Todos los demás endpoints requieren un token bearer.

curl https://imgpile.com/api/v1/posts

Para solicitudes autenticadas, pasa tu token en el Authorization encabezado:

curl -H "Authorization: Bearer YOUR_TOKEN" https://cdn.imgpile.com/api/v1/media -F "[email protected]"

El destino de las cargas de archivos cdn.imgpile.com; ver Media → Upload para más detalles.

Genera un token en la Introducción sección de arriba.

Errores

La API devuelve códigos de estado HTTP estándar. Las respuestas de error incluyen un cuerpo JSON con un campo que describe message (o error) qué salió mal.

Códigos de estado

Código	Significado
`200`	OK — la solicitud se realizó correctamente
`201`	Created — se creó el recurso
`400`	Bad Request — solicitud mal formada
`401`	Unauthenticated — falta el token o es inválido
`403`	Prohibido — no tienes permiso para esta acción
`404`	No encontrado — el recurso no existe
`422`	Validation failed — el cuerpo de la solicitud tiene campos inválidos
`429`	Rate Limited — demasiadas solicitudes, baja el ritmo
`451`	Unavailable for Legal Reasons — el archivo coincide con un hash prohibido
`500`	Server Error — algo salió mal de nuestro lado

Ejemplos de respuestas de error

401 Unauthenticated

{ "message": "Unauthenticated." }

403 Forbidden

{ "message": "This action is unauthorized." }

422 Validation failed

{
  "message": "The file field is required.",
  "errors": {
    "file": ["The file field is required."]
  }
}

429 Rate limited

{ "message": "Too Many Attempts." }

Consulta el Retry-After encabezado de la respuesta para los segundos hasta que se restablezca el límite.

451 Contenido prohibido

{ "error": "This file is not allowed." }

Paginación de la API

Listar endpoints (GET /posts, GET /media) devuelve resultados paginados. El tamaño de página predeterminado es 10; puedes solicitar hasta 250 con ?limit=N.

Usa ?page=N para navegar por las páginas. La respuesta incluye metadatos de paginación:

{
  "data": [ ... ],
  "links": {
    "first": "https://imgpile.com/api/v1/posts?page=1",
    "last": "https://imgpile.com/api/v1/posts?page=42",
    "prev": null,
    "next": "https://imgpile.com/api/v1/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 10,
    "per_page": 10,
    "total": 421,
    "last_page": 42
  }
}

Al iterar, sigue links.next hasta que sea null, o consulta meta.current_page contra meta.last_page.

Filtrado de contenido

De forma predeterminada, lista endpoints (GET /posts, GET /media) solo devuelve contenido seguro (estado de moderación approved). Para incluir también contenido para adultos (nsfw), pasar ?nsfw=1:

curl https://imgpile.com/api/v1/posts?nsfw=1

Contenido prohibido (rejected, es decir, spam o abuso) nunca se devuelve a los endpoints públicos de feed, independientemente de la ?nsfw bandera.

Cada respuesta de publicación y de medios incluye un moderation_status campo para que puedas avisar, difuminar u ocultar los elementos marcados en tu cliente:

{
  "moderation_status": "approved" | "pending" | "nsfw" | "rejected",
  ...
}

approved — seguro para todo tipo de público.
pending — en espera de moderación automatizada.
nsfw — contenido para adultos; solo se devuelve desde endpoints públicos cuando ?nsfw=1.
rejected — spam/abuso; nunca se devuelve a endpoints públicos.

Publicaciones ocultas se pueden acceder por su slug, pero nunca aparecen en los feeds. Publicaciones privadas requieren un ?key=xxx parámetro de consulta (el propietario puede encontrarlo en el enlace de compartido de la publicación).

Límites de velocidad

Solicitudes públicas (sin token): 30 solicitudes/minuto por IP
Solicitudes autenticadas: 120 solicitudes/minuto por usuario
Subidas de archivos: 1.000 archivos/día por usuario/IP
Tamaño máximo de archivo: 100 MB
Tipos aceptados: image/* y video/*

Los encabezados de límite de velocidad se incluyen en cada respuesta (X-RateLimit-Limit, X-RateLimit-Remaining).

El objeto Media

Devuelto por los endpoints de medios e incrustado dentro de las respuestas de publicaciones.

Campo	Tipo	Descripción
slug	`string`	Identificador único de 7 caracteres. Usado en URLs.
filename	`string`	Nombre de archivo en el almacenamiento (igual que el slug).
title	`string\|null`	Título proporcionado por el usuario.
description	`string\|null`	Descripción proporcionada por el usuario.
type	`string`	tipo MIME — p. ej. `image/jpeg`, `video/mp4`.
width	`integer`	Ancho en píxeles.
height	`integer`	Alto en píxeles.
moderation_status	`enum`	Uno de `approved`, `pending`, `nsfw`, o `rejected`. Ver Filtrado de contenido.
processed	`boolean`	`false` mientras se generan las variantes con tamaño; `true` cuando esté listo.
created_at	`timestamp`	marca de tiempo ISO 8601.
urls	`object`	URLs del CDN en cada tamaño disponible — ver URLs directas de imágenes.
user	`object\|null`	El uploader (nombre de usuario, avatar). Null para subidas de invitados.

El objeto Post

Un contenedor compartible para uno o más elementos multimedia.

Campo	Tipo	Descripción
id	`integer`	ID numérico. Usa `slug` para URLs.
slug	`string`	Identificador único de 7 caracteres. Usado en URLs.
title	`string\|null`	Título de la publicación.
description	`string\|null`	Descripción de la publicación.
score	`integer`	Puntuación neta de votos (votos a favor menos votos en contra).
view_count	`integer`	Total de visitas a la página.
media_count	`integer`	Número de elementos multimedia en esta publicación.
moderation_status	`enum`	Uno de `approved`, `pending`, `nsfw`, o `rejected`. Ver Filtrado de contenido.
isUpvotedByUser	`boolean`	Si el usuario autenticado ha votado a favor esta publicación.
isDownvotedByUser	`boolean`	Si el usuario autenticado ha votado en contra esta publicación.
created_at	`timestamp`	marca de tiempo ISO 8601.
user	`object\|null`	El autor (nombre de usuario, avatar). Null para publicaciones de invitados.
media	`array`	Array de Objetos multimedia. Solo incluido en solicitudes de una publicación.
first_media	`object\|null`	El primer medio (vista previa). Solo incluido en respuestas del feed.
Campos solo para el propietario (se devuelven únicamente al propietario de la publicación):
visibility	`enum`	`public`, `hidden`, o `private`.
access_key	`string\|null`	Requerido para ver una publicación privada. Añade como `?key=xxx`.

Endpoints de Media

Archivos individuales (imágenes o videos). Cada medio tiene una URL directa del CDN que puedes enlazar en caliente o incrustar en cualquier lugar.

POST /media Se requiere autenticación

Host de carga

Enviar subidas a https://cdn.imgpile.com/api/v1/media — no imgpile.com. Los archivos se almacenan en un origen dedicado; hacer POST al host principal fallará.

El resto de endpoints usa imgpile.com/api/v1 como de costumbre.

Sube una imagen o video. Enviar como multipart/form-data.

Parámetro	Descripción
filerequerido	El archivo a subir. Máx. 100 MB. Acepta image/* y video/*.
post_idopcional	Adjuntar a una publicación existente.

Solicitud

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Respuesta 201

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "filename": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

GET /media Público

Lista elementos multimedia con filtrado y paginación.

Parámetro	Descripción
tag	Filtrar por nombre de etiqueta
sort	`latest` (predeterminado) o `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Resultados por página (máx. 250, predeterminado 10)
username	Filtrar por nombre de usuario
nsfw	Establecer en `1` para incluir contenido NSFW. Predeterminado: solo SFW.

Solicitud

curl https://imgpile.com/api/v1/media?limit=20

Respuesta 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ],
  "links": { ... },
  "meta": { "current_page": 1, "total": 421 }
}

GET /media/{slug} Público

Obtén un solo elemento multimedia por su slug.

Solicitud

curl https://imgpile.com/api/v1/media/abc1234

Respuesta 200

{
  "data": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": { ... }
  }
}

PATCH /media/{slug} Se requiere autenticación

Actualiza los medios que posees.

Parámetro	Descripción
title	Título del medio
description	Descripción del medio

Solicitud

curl -X PATCH https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

Respuesta 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Se requiere autenticación

Elimina los medios que posees.

Solicitud

curl -X DELETE https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "Media deleted successfully."
}

Endpoints de Post

Páginas compartibles que contienen uno o más elementos multimedia. Tienen un título, descripción, votaciones, comentarios y etiquetas.

GET /posts Público

Lista publicaciones públicas con filtrado y paginación.

Parámetro	Descripción
tag	Filtrar por nombre de etiqueta
sort	`latest` (predeterminado) o `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Resultados por página (máx. 250, predeterminado 10)
username	Filtrar por nombre de usuario
nsfw	Establecer en `1` para incluir contenido NSFW. Predeterminado: solo SFW.

Solicitud

curl https://imgpile.com/api/v1/posts?sort=latest

Respuesta 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "view_count": 245,
      "media_count": 3,
      "moderation_status": "approved",
      "user": { "username": "alice", ... },
      "first_media": { ... }
    },
    ...
  ]
}

GET /posts/{slug} Público

Obtén una sola publicación con medios paginados.

Parámetro	Descripción
mediaPage	Número de página para los medios (predeterminado 1)
perPage	Elementos de medios por página (predeterminado 10)
key	Requerido para publicaciones privadas. El propietario puede encontrarlo en el enlace de compartido.

Solicitud

curl https://imgpile.com/api/v1/posts/MSGhYqy

# Private post with key:
curl "https://imgpile.com/api/v1/posts/xyz789?key=ab12cd34ef"

Respuesta 200

{
  "data": {
    "id": 30713,
    "slug": "MSGhYqy",
    "title": "Sunset photos",
    "description": "...",
    "score": 12,
    "view_count": 245,
    "moderation_status": "approved",
    "user": { "username": "alice", ... },
    "media": [ ... ]
  }
}

POST /posts Se requiere autenticación

Crea una nueva publicación a partir de los medios subidos.

Parámetro	Descripción
media_idsrequerido	Matriz de IDs de medios para incluir en la publicación

Solicitud

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'

Respuesta 201

{
  "message": "Post created successfully",
  "post": {
    "id": 30720,
    "slug": "rtWJdHr"
  }
}

PATCH /posts/{slug} Se requiere autenticación

Actualiza una publicación que te pertenece.

Parámetro	Descripción
title	Título de la publicación (máx. 255)
description	Descripción de la publicación
visibility	`public`, `hidden`, o `private`. Configuración para `private` genera automáticamente un `access_key`.
is_nsfw	Booleano. Marca la publicación como contenido para adultos para que quede oculta detrás del botón NSFW del visor. Una vez configurado, la publicación no se resolverá automáticamente por debajo de `nsfw`.
media_order	Matriz de slugs de medios en el orden deseado

Solicitud

curl -X PATCH https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "visibility": "private"}'

Respuesta 200

{
  "message": "Post updated successfully",
  "visibility": "private",
  "access_key": "ab12cd34ef"
}

DELETE /posts/{slug} Se requiere autenticación

Elimina una publicación que te pertenece.

Solicitud

curl -X DELETE https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "Post deleted successfully"
}

Comentarios

POST /posts/{post}/comments Se requiere autenticación

Añade un comentario a una publicación.

Parámetro	Descripción
contentrequerido	Texto del comentario (máx. 500 caracteres)
parent_idopcional	ID del comentario al que responder (para respuestas en hilo)

Solicitud

curl -X POST https://imgpile.com/api/v1/posts/MSGhYqy/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Nice shot!"}'

Respuesta 201

{
  "success": true,
  "comment": {
    "id": 456,
    "content": "Nice shot!",
    "user_id": 1,
    "post_id": 12345
  }
}

DELETE /comments/{comment} Se requiere autenticación

Elimina un comentario que te pertenece.

Solicitud

curl -X DELETE https://imgpile.com/api/v1/comments/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "success": true,
  "message": "Comment deleted successfully"
}

Usuarios

GET /users/{username}/posts Público

Obtén las publicaciones de un usuario.

Solicitud

curl https://imgpile.com/api/v1/users/alice/posts

Respuesta 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "moderation_status": "approved",
      "first_media": { ... }
    },
    ...
  ]
}

GET /users/{username}/media Público

Obtén los medios de un usuario.

Solicitud

curl https://imgpile.com/api/v1/users/alice/media

Respuesta 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ]
}

GET /users/{username}/comments Público

Obtén los comentarios de un usuario (paginado).

Solicitud

curl https://imgpile.com/api/v1/users/alice/comments

GET /users/{username}/followers Público

Obtén los seguidores de un usuario (paginado).

Solicitud

curl https://imgpile.com/api/v1/users/alice/followers

GET /users/{username}/following Público

Obtén los usuarios a los que sigue este usuario (paginado).

Solicitud

curl https://imgpile.com/api/v1/users/alice/following

POST /users/{username}/follow Se requiere autenticación

Seguir a un usuario.

Solicitud

curl -X POST https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Se requiere autenticación

Dejar de seguir a un usuario.

Solicitud

curl -X DELETE https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "User unfollowed."
}

Votaciones

POST /posts/{post}/upvote Se requiere autenticación

Dar un voto a favor a una publicación. Si lo llamas de nuevo, se elimina el voto a favor.

Solicitud

curl -X POST https://imgpile.com/api/v1/posts/123/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "Post upvoted successfully",
  "score": 13
}

POST /posts/{post}/downvote Se requiere autenticación

Dar un voto en contra a una publicación. Si lo llamas de nuevo, se elimina el voto en contra.

Solicitud

curl -X POST https://imgpile.com/api/v1/posts/123/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta 200

{
  "message": "Post downvoted successfully",
  "score": 11
}

POST /comments/{comment}/upvote Se requiere autenticación

Dar un voto a favor a un comentario. Si lo llamas de nuevo, se elimina el voto a favor.

Solicitud

curl -X POST https://imgpile.com/api/v1/comments/456/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /comments/{comment}/downvote Se requiere autenticación

Dar un voto en contra a un comentario. Si lo llamas de nuevo, se elimina el voto en contra.

Solicitud

curl -X POST https://imgpile.com/api/v1/comments/456/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

URLs directas de imágenes

Cada archivo subido se sirve a través de la CDN. La respuesta del medio incluye un urls objeto con todos los tamaños disponibles:

https://cdn.imgpile.com/f/{filename}.{ext}          — Original
https://cdn.imgpile.com/f/{filename}_xs.{ext}       — Extra small
https://cdn.imgpile.com/f/{filename}_sm.{ext}       — Small
https://cdn.imgpile.com/f/{filename}_md.{ext}       — Medium
https://cdn.imgpile.com/f/{filename}_lg.{ext}       — Large
https://cdn.imgpile.com/f/{filename}_xl.{ext}       — Extra large
https://cdn.imgpile.com/f/{filename}_thumb.jpg      — Thumbnail (videos)