API imgpile

Carica, condividi e gestisci immagini e video in modo programmatico.

https://imgpile.com/api/v1 — tutti gli endpoint

https://cdn.imgpile.com/api/v1/media — solo caricamenti di file (vedi sotto)

Ottieni un token API

Accedi oppure registrati per generare un token API.

Concetti

imgpile ha due oggetti principali. Capire la differenza ti farà risparmiare tempo.

Media

Un singolo file (immagine o video). Ha un URL CDN diretto, ideale per hotlinking, embedding o condivisione.

Post

Una pagina condivisibile che contiene uno o più elementi multimediali. Ha un titolo, una descrizione, votazioni, commenti e tag.

Ti serve solo un URL diretto dell'immagine? Carica su /media. Usa urls.original dalla risposta. Fatto.

Vuoi un post condivisibile con commenti e votazioni? Carica prima i contenuti multimediali, poi chiama /posts con gli ID dei media.

Avvio rapido

Carica un singolo file e ottieni un URL CDN diretto. Perfetto per ShareX, bot di Discord o qualsiasi script che deve solo ospitare un'immagine.

Nota: i caricamenti vanno su cdn.imgpile.com, non imgpile.com.

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

Risposta:

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

Carica più file, poi raggruppali in un post con metadati, voti e commenti.

1. Carica ogni file su cdn.imgpile.com e conserva l'ID del media restituito:

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

2. Crea un post con quegli ID:

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. (Opzionale) Aggiungi un titolo e una descrizione:

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

Il tuo post è ora online su https://imgpile.com/p/xyz789

Carica un'immagine da un browser o da 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

Configurazione di ShareX

Scarica la nostra configurazione per Custom Uploader e importala in ShareX: non serve modificare manualmente il JSON.

Scarica imgpile.sxcu

Fai clic sul pulsante qui sopra per scaricare imgpile.sxcu.
Doppio clic sul file — ShareX lo importerà e renderà imgpile disponibile un uploader.
Apri Destinazioni → Impostazioni uploader personalizzato → Intestazioni e sostituisci YOUR_TOKEN_HERE con il tuo token API (ne puoi generare uno nella Introduzione).
Imposta Destinazioni → Image uploader → imgpile. Cattura uno screenshot — l'URL finirà negli appunti come https://cdn.imgpile.com/f/….

Autenticazione

Gli endpoint di lettura (GET) sono pubblici e non richiedono autenticazione. Tutti gli altri endpoint richiedono un bearer token.

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

Per richieste autenticate, passa il tuo token nell' Authorization header:

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

I caricamenti file puntano a cdn.imgpile.com; vedi Media → Upload per i dettagli.

Genera un token nella Introduzione sezione qui sopra.

Errori

La API restituisce codici di stato HTTP standard. Le risposte di errore includono un body JSON con un campo message (oppure error) che descrive cosa è andato storto.

Codici di stato

Codice	Significato
`200`	OK — richiesta riuscita
`201`	Creato — risorsa creata
`400`	Bad Request — richiesta malformata
`401`	Non autenticata — token mancante o non valido
`403`	Vietato — non hai i permessi per questa azione
`404`	Non trovato — la risorsa non esiste
`422`	Validazione fallita — il body della richiesta ha campi non validi
`429`	Limitato — troppe richieste, rallenta
`451`	Non disponibile per motivi legali — il file corrisponde a un hash bloccato
`500`	Errore del server — qualcosa è andato storto da parte nostra

Esempi di risposte di errore

401 Non autenticata

{ "message": "Unauthenticated." }

403 Vietato

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

422 Validazione fallita

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

429 Limitato

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

Controlla l' Retry-After header della risposta per i secondi fino al reset del limite.

Contenuto vietato 451

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

Impaginazione API

Elenca endpoint (GET /posts, GET /media) restituisce risultati impaginati. La dimensione predefinita della pagina è 10; puoi richiedere fino a 250 con ?limit=N.

Usa ?page=N per navigare tra le pagine. La risposta include i metadati di impaginazione:

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

Quando scorre, segui links.next finché non è null, oppure controlla meta.current_page rispetto a meta.last_page.

Filtraggio dei contenuti

Per impostazione predefinita, elenca gli endpoint (GET /posts, GET /media) restituiscono solo contenuti sicuri (stato della moderazione approved). Per includere anche contenuti per adulti (nsfw), passa ?nsfw=1:

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

Contenuto vietato (rejected, cioè spam o abusi) non viene mai restituito agli endpoint pubblici dei feed, indipendentemente da ?nsfw flag.

Ogni risposta di post e media include un moderation_status campo così puoi avvisare, sfocare o nascondere gli elementi segnalati nel tuo client:

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

approved — sicuro per tutti i pubblici.
pending — in attesa di moderazione automatizzata.
nsfw — contenuti per adulti; restituiti solo dagli endpoint pubblici quando ?nsfw=1.
rejected — spam/abusi; mai restituiti agli endpoint pubblici.

Post nascosti sono accessibili tramite lo slug ma non compaiono mai nei feed. Post privati richiedono un ?key=xxx parametro di query (il proprietario può trovarlo nel link di condivisione del post).

Limiti di velocità

Richieste pubbliche (senza token): 30 richieste/minuto per IP
Richieste autenticare: 120 richieste/minuto per utente
Caricamenti di file: 1.000 file/giorno per utente/IP
Dimensione massima del file: 100 MB
Tipi accettati: image/* e video/*

Gli header dei limiti di velocità sono inclusi in ogni risposta (X-RateLimit-Limit, X-RateLimit-Remaining).

L'oggetto Media

Restituiti dagli endpoint dei media e incorporati nelle risposte dei post.

Campo	Tipo	Descrizione
slug	`string`	Identificatore univoco di 7 caratteri. Usato negli URL.
filename	`string`	Nome file di archiviazione (uguale allo slug).
title	`string\|null`	Titolo fornito dall'utente.
description	`string\|null`	Descrizione fornita dall'utente.
type	`string`	Tipo MIME — ad es. `image/jpeg`, `video/mp4`.
width	`integer`	Larghezza in pixel.
height	`integer`	Altezza in pixel.
moderation_status	`enum`	Uno di `approved`, `pending`, `nsfw`, oppure `rejected`. Vedi Filtraggio dei contenuti.
processed	`boolean`	`false` mentre vengono generate le varianti dimensionate; `true` quando è pronto.
created_at	`timestamp`	timestamp ISO 8601.
urls	`object`	URL CDN a ogni dimensione disponibile — vedi URL diretti delle immagini.
user	`object\|null`	Il caricatore (username, avatar). Null per i caricamenti ospite.

L'oggetto Post

Un contenitore condivisibile per uno o più elementi multimediali.

Campo	Tipo	Descrizione
id	`integer`	ID numerico. Usa `slug` per gli URL.
slug	`string`	Identificatore univoco di 7 caratteri. Usato negli URL.
title	`string\|null`	Titolo del post.
description	`string\|null`	Descrizione del post.
score	`integer`	Punteggio voti netto (voti a favore meno voti contrari).
view_count	`integer`	Visualizzazioni totali della pagina.
media_count	`integer`	Numero di elementi multimediali in questo post.
moderation_status	`enum`	Uno di `approved`, `pending`, `nsfw`, oppure `rejected`. Vedi Filtraggio dei contenuti.
isUpvotedByUser	`boolean`	Se l'utente autenticato ha votato a favore questo post.
isDownvotedByUser	`boolean`	Se l'utente autenticato ha votato contro questo post.
created_at	`timestamp`	timestamp ISO 8601.
user	`object\|null`	L'autore (username, avatar). Null per i post ospite.
media	`array`	Array di Oggetti multimediali. Incluso solo nelle richieste di singolo post.
first_media	`object\|null`	Il primo elemento multimediale (anteprima). Inclusa solo nelle risposte del feed.
Campi solo per il proprietario (restituiti solo al proprietario del post):
visibility	`enum`	`public`, `hidden`, oppure `private`.
access_key	`string\|null`	Richiesto per visualizzare un post privato. Aggiungi come `?key=xxx`.

Endpoint dei Media

Singoli file (immagini o video). Ogni elemento multimediale ha un URL CDN diretto che puoi hotlinkare o incorporare ovunque.

POST /media Autenticazione richiesta

Host di upload

Invia gli upload a https://cdn.imgpile.com/api/v1/media — non imgpile.com. I file vengono salvati su un'origine dedicata; fare POST sull'host principale fallirà.

Tutti gli altri endpoint usano imgpile.com/api/v1 come al solito.

Carica un'immagine o un video. Invia come multipart/form-data.

Parametro	Descrizione
fileobbligatorio	Il file da caricare. Max 100 MB. Accetta image/* e video/*.
post_idopzionale	Allega a un post esistente.

Richiesta

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

Risposta 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 Pubblico

Elenca gli elementi multimediali con filtri e paginazione.

Parametro	Descrizione
tag	Filtra per nome tag
sort	`latest` (predefinito) o `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Risultati per pagina (max 250, predefinito 10)
username	Filtra per username
nsfw	Imposta su `1` per includere contenuti NSFW. Predefinito: solo SFW.

Richiesta

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

Risposta 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} Pubblico

Ottieni un singolo elemento multimediale tramite il suo slug.

Richiesta

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

Risposta 200

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

PATCH /media/{slug} Autenticazione richiesta

Aggiorna i contenuti multimediali che possiedi.

Parametro	Descrizione
title	Titolo del contenuto multimediale
description	Descrizione del contenuto multimediale

Richiesta

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

Risposta 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Autenticazione richiesta

Elimina i contenuti multimediali che possiedi.

Richiesta

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

Risposta 200

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

Endpoint dei Post

Pagine condivisibili che contengono uno o più elementi multimediali. Hanno un titolo, una descrizione, votazioni, commenti e tag.

GET /posts Pubblico

Elenca i post pubblici con filtri e paginazione.

Parametro	Descrizione
tag	Filtra per nome tag
sort	`latest` (predefinito) o `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Risultati per pagina (max 250, predefinito 10)
username	Filtra per username
nsfw	Imposta su `1` per includere contenuti NSFW. Predefinito: solo SFW.

Richiesta

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

Risposta 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} Pubblico

Ottieni un singolo post con media impaginati.

Parametro	Descrizione
mediaPage	Numero di pagina per i media (predefinito 1)
perPage	Elementi media per pagina (predefinito 10)
key	Richiesto per i post privati. Il proprietario può trovarlo nel link di condivisione.

Richiesta

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

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

Risposta 200

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

POST /posts Autenticazione richiesta

Crea un nuovo post a partire dai media caricati.

Parametro	Descrizione
media_idsobbligatorio	Array di ID dei media da includere nel post

Richiesta

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

Risposta 201

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

PATCH /posts/{slug} Autenticazione richiesta

Aggiorna un post di tua proprietà.

Parametro	Descrizione
title	Titolo del post (max 255)
description	Descrizione del post
visibility	`public`, `hidden`, oppure `private`. Impostazione per `private` genera automaticamente un `access_key`.
is_nsfw	Booleano. Contrassegna il post come contenuto per adulti così sarà bloccato dietro l'interruttore NSFW dello spettatore. Una volta impostato, il post non verrà risolto automaticamente sotto `nsfw`.
media_order	Array di slug dei media nell'ordine desiderato

Richiesta

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

Risposta 200

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

DELETE /posts/{slug} Autenticazione richiesta

Elimina un post di tua proprietà.

Richiesta

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

Risposta 200

{
  "message": "Post deleted successfully"
}

Commenti

POST /posts/{post}/comments Autenticazione richiesta

Aggiungi un commento a un post.

Parametro	Descrizione
contentobbligatorio	Testo del commento (max 500 caratteri)
parent_idopzionale	ID del commento a cui rispondere (per risposte in thread)

Richiesta

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

Risposta 201

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

DELETE /comments/{comment} Autenticazione richiesta

Elimina un commento di tua proprietà.

Richiesta

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

Risposta 200

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

Utenti

GET /users/{username}/posts Pubblico

Ottieni i post di un utente.

Richiesta

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

Risposta 200

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

GET /users/{username}/media Pubblico

Ottieni i media di un utente.

Richiesta

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

Risposta 200

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

GET /users/{username}/comments Pubblico

Ottieni i commenti di un utente (impaginati).

Richiesta

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

GET /users/{username}/followers Pubblico

Ottieni i follower di un utente (impaginati).

Richiesta

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

GET /users/{username}/following Pubblico

Ottieni gli utenti che questo utente sta seguendo (impaginati).

Richiesta

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

POST /users/{username}/follow Autenticazione richiesta

Segui un utente.

Richiesta

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

Risposta 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Autenticazione richiesta

Smetti di seguire un utente.

Richiesta

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

Risposta 200

{
  "message": "User unfollowed."
}

Votazioni

POST /posts/{post}/upvote Autenticazione richiesta

Vota in alto un post. Chiamare di nuovo rimuove il voto positivo.

Richiesta

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

Risposta 200

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

POST /posts/{post}/downvote Autenticazione richiesta

Vota in basso un post. Chiamare di nuovo rimuove il voto negativo.

Richiesta

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

Risposta 200

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

POST /comments/{comment}/upvote Autenticazione richiesta

Vota in alto un commento. Chiamare di nuovo rimuove il voto positivo.

Richiesta

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

POST /comments/{comment}/downvote Autenticazione richiesta

Vota in basso un commento. Chiamare di nuovo rimuove il voto negativo.

Richiesta

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

URL diretti delle immagini

Ogni file caricato viene servito tramite la CDN. La risposta del media include un urls oggetto con tutte le dimensioni disponibili:

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)