API imgpile

Téléversez, partagez et gérez des images et des vidéos par programmation.

https://imgpile.com/api/v1 — tous les endpoints

https://cdn.imgpile.com/api/v1/media — téléversements de fichiers uniquement (voir ci-dessous)

Obtenir un jeton API

Se connecter ou s'inscrire pour générer un jeton API.

Concepts

imgpile dispose de deux objets principaux. Comprendre la différence vous fera gagner du temps.

Médias

Un seul fichier (image ou vidéo). A une URL CDN directe — idéale pour le hotlinking, l'intégration ou le partage.

Publication

Une page partageable contenant un ou plusieurs éléments multimédias. Elle a un titre, une description, des votes, des commentaires et des tags.

Vous avez juste besoin d'une URL d'image directe ? Téléverser vers /media. Utiliser urls.original depuis la réponse. C'est fait.

Vous voulez une publication partageable avec des commentaires et des votes ? Téléversez d'abord les médias, puis appelez /posts avec les ID des médias.

Démarrage rapide

Uploadez un seul fichier et obtenez une URL CDN directe. Parfait pour ShareX, les bots Discord, ou tout script qui a juste besoin d'héberger une image.

Note : les uploads vont vers cdn.imgpile.com, pas imgpile.com.

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

Réponse :

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

Uploadez plusieurs fichiers, puis regroupez-les dans un post avec des métadonnées, un vote et des commentaires.

1. Uploadez chaque fichier sur cdn.imgpile.com et conservez l'ID média renvoyé :

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

2. Créez un post avec ces 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. (Optionnel) Ajoutez un titre et une description :

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

Votre post est maintenant en ligne à https://imgpile.com/p/xyz789

Uploadez une image depuis un navigateur ou 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

Configuration de ShareX

Téléchargez notre configuration de Custom Uploader et importez-la dans ShareX — aucune édition manuelle du JSON nécessaire.

Télécharger imgpile.sxcu

Cliquez sur le bouton ci-dessus pour télécharger imgpile.sxcu.
Double-cliquez sur le fichier — ShareX va l'importer et faire imgpile un uploader disponible.
Ouvrir Destinations → Paramètres de l'uploader personnalisé → Headers et remplacez YOUR_TOKEN_HERE par votre token API (générez-en un dans la Introduction).
Définir Destinations → Image uploader → imgpile. Faites une capture d'écran — l'URL sera copiée dans votre presse-papiers en tant que https://cdn.imgpile.com/f/….

Authentification

Les endpoints en lecture (GET) sont publics et ne nécessitent pas d'authentification. Tous les autres endpoints nécessitent un jeton porteur (bearer token).

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

Pour les requêtes authentifiées, passez votre token dans le Authorization header :

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

Cible des uploads de fichiers cdn.imgpile.com; voir Médias → Upload pour plus de détails.

Générez un token dans la Introduction section ci-dessus.

Erreurs

L'API renvoie des codes de statut HTTP standards. Les réponses d'erreur incluent un corps JSON avec un message (ou error) champ décrivant ce qui s'est mal passé.

Codes de statut

Code	Signification
`200`	OK — la requête a réussi
`201`	Created — la ressource a été créée
`400`	Bad Request — requête mal formée
`401`	Unauthenticated — token manquant ou invalide
`403`	Interdit — vous n'avez pas la permission pour cette action
`404`	Introuvable — la ressource n'existe pas
`422`	Validation failed — le corps de la requête contient des champs invalides
`429`	Rate Limited — trop de requêtes, ralentissez
`451`	Unavailable for Legal Reasons — le fichier correspond à un hash banni
`500`	Server Error — quelque chose s'est mal passé de notre côté

Exemples de réponses d'erreur

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

Vérifiez l'en-tête de Retry-After réponse pendant le nombre de secondes jusqu'à la réinitialisation de la limite.

451 Contenu interdit

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

Pagination de l'API

Lister les endpoints (GET /posts, GET /media) renvoie des résultats paginés. La taille de page par défaut est de 10 ; vous pouvez en demander jusqu'à 250 avec ?limit=N.

Utiliser ?page=N pour naviguer entre les pages. La réponse inclut des métadonnées de pagination :

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

Lors de l'itération, suivez links.next jusqu'à ce que ce soit null, ou vérifiez meta.current_page par rapport à meta.last_page.

Filtrage du contenu

Par défaut, lister les endpoints (GET /posts, GET /media) ne renvoie que du contenu sûr (statut de modération approved). Pour inclure aussi le contenu adulte (nsfw), pass ?nsfw=1:

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

Contenu interdit (rejected, c.-à-d. le spam ou les abus) n'est jamais renvoyé aux endpoints de flux publics, quelle que soit la ?nsfw valeur.

Chaque réponse de publication et de média inclut un moderation_status champ afin que vous puissiez avertir, flouter ou masquer les éléments signalés dans votre client :

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

approved — sûr pour tous les publics.
pending — en attente de modération automatisée.
nsfw — contenu adulte ; renvoyé uniquement depuis les endpoints publics lorsque ?nsfw=1.
rejected — spam/abus ; jamais renvoyé aux endpoints publics.

Publications masquées sont accessibles via leur slug, mais n'apparaissent jamais dans les flux. Publications privées nécessitent un ?key=xxx paramètre de requête (le propriétaire peut le trouver dans le lien de partage du post).

Limites de débit

Requêtes publiques (sans jeton) : 30 requêtes/minute par IP
Requêtes authentifiées: 120 requêtes/minute par utilisateur
Envois de fichiers: 1 000 fichiers/jour par utilisateur/IP
Taille maximale du fichier: 100 Mo
Types acceptés: image/* et video/*

Les en-têtes de limitation de débit sont inclus dans chaque réponse (X-RateLimit-Limit, X-RateLimit-Remaining).

L'objet Media

Renvoyé par les endpoints de média et intégré dans les réponses de publication.

Champ	Type	Description
slug	`string`	Identifiant unique de 7 caractères. Utilisé dans les URL.
filename	`string`	Nom de fichier de stockage (identique au slug).
title	`string\|null`	Titre fourni par l'utilisateur.
description	`string\|null`	Description fournie par l'utilisateur.
type	`string`	Type MIME — par ex. `image/jpeg`, `video/mp4`.
width	`integer`	Largeur en pixels.
height	`integer`	Hauteur en pixels.
moderation_status	`enum`	L'un de `approved`, `pending`, `nsfw`, ou `rejected`. Voir Filtrage du contenu.
processed	`boolean`	`false` pendant que les variantes de taille sont en cours de génération ; `true` quand c'est prêt.
created_at	`timestamp`	horodatage ISO 8601.
urls	`object`	URLs CDN à chaque taille disponible — voir URL d'images directes.
user	`object\|null`	L'uploader (nom d'utilisateur, avatar). Null pour les envois en tant qu'invité.

L'objet Post

Un conteneur partageable pour un ou plusieurs éléments multimédias.

Champ	Type	Description
id	`integer`	ID numérique. Utilisez `slug` pour les URLs.
slug	`string`	Identifiant unique de 7 caractères. Utilisé dans les URL.
title	`string\|null`	Titre du post.
description	`string\|null`	Description du post.
score	`integer`	Score net des votes (votes positifs moins votes négatifs).
view_count	`integer`	Nombre total de vues de page.
media_count	`integer`	Nombre d'éléments multimédias dans ce post.
moderation_status	`enum`	L'un de `approved`, `pending`, `nsfw`, ou `rejected`. Voir Filtrage du contenu.
isUpvotedByUser	`boolean`	Indique si l'utilisateur authentifié a voté positivement ce post.
isDownvotedByUser	`boolean`	Indique si l'utilisateur authentifié a voté négativement ce post.
created_at	`timestamp`	horodatage ISO 8601.
user	`object\|null`	L'auteur (nom d'utilisateur, avatar). Null pour les posts en tant qu'invité.
media	`array`	Tableau de Objets multimédias. Inclus uniquement dans les requêtes pour un seul post.
first_media	`object\|null`	Le premier média (aperçu). Inclus uniquement dans les réponses du flux.
Champs réservés au propriétaire (renvoyés uniquement au propriétaire du post) :
visibility	`enum`	`public`, `hidden`, ou `private`.
access_key	`string\|null`	Requis pour voir un post privé. À ajouter comme `?key=xxx`.

Endpoints Media

Fichiers individuels (images ou vidéos). Chaque média a une URL CDN directe que vous pouvez hotlink ou intégrer n'importe où.

POST /media Authentification requise

Hôte d'envoi

Envoyer les envois vers https://cdn.imgpile.com/api/v1/media — pas imgpile.com. Les fichiers sont stockés sur une origine dédiée ; faire un POST vers l'hôte principal échouera.

Tous les autres endpoints utilisent imgpile.com/api/v1 comme d'habitude.

Envoyer une image ou une vidéo. Envoyer en tant que multipart/form-data.

Paramètre	Description
filerequis	Le fichier à envoyer. Max 100 Mo. Accepte image/* et video/*.
post_idoptionnel	Joindre à un post existant.

Requête

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

Réponse 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 Public

Lister les éléments multimédias avec filtrage et pagination.

Paramètre	Description
tag	Filtrer par nom de tag
sort	`latest` (par défaut) ou `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Résultats par page (max 250, par défaut 10)
username	Filtrer par nom d'utilisateur
nsfw	Définir sur `1` pour inclure le contenu NSFW. Par défaut : SFW uniquement.

Requête

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

Réponse 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} Public

Obtenir un seul élément multimédia via son slug.

Requête

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

Réponse 200

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

PATCH /media/{slug} Authentification requise

Mettre à jour les médias que vous possédez.

Paramètre	Description
title	Titre du média
description	Description du média

Requête

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

Réponse 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Authentification requise

Supprimer les médias que vous possédez.

Requête

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

Réponse 200

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

Endpoints Post

Pages partageables qui contiennent un ou plusieurs éléments multimédias. Elles ont un titre, une description, des votes, des commentaires et des tags.

GET /posts Public

Lister les posts publics avec filtrage et pagination.

Paramètre	Description
tag	Filtrer par nom de tag
sort	`latest` (par défaut) ou `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Résultats par page (max 250, par défaut 10)
username	Filtrer par nom d'utilisateur
nsfw	Définir sur `1` pour inclure le contenu NSFW. Par défaut : SFW uniquement.

Requête

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

Réponse 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} Public

Obtenir un seul post avec des médias paginés.

Paramètre	Description
mediaPage	Numéro de page pour les médias (par défaut 1)
perPage	Nombre d'éléments média par page (par défaut 10)
key	Requis pour les posts privés. Le propriétaire peut le trouver dans le lien de partage.

Requête

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

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

Réponse 200

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

POST /posts Authentification requise

Créer un nouveau post à partir des médias téléversés.

Paramètre	Description
media_idsrequis	Tableau d'IDs des médias à inclure dans le post

Requête

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

Réponse 201

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

PATCH /posts/{slug} Authentification requise

Mettre à jour un post que vous possédez.

Paramètre	Description
title	Titre du post (max 255)
description	Description du post
visibility	`public`, `hidden`, ou `private`. Paramètre pour `private` génère automatiquement un `access_key`.
is_nsfw	Booléen. Marquer le post comme contenu pour adultes pour qu'il soit masqué derrière l'option NSFW du spectateur. Une fois défini, le post ne sera pas automatiquement résolu en dessous de `nsfw`.
media_order	Tableau des slugs des médias dans l'ordre souhaité

Requête

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

Réponse 200

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

DELETE /posts/{slug} Authentification requise

Supprimer un post que vous possédez.

Requête

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

Réponse 200

{
  "message": "Post deleted successfully"
}

Commentaires

POST /posts/{post}/comments Authentification requise

Ajouter un commentaire à un post.

Paramètre	Description
contentrequis	Texte du commentaire (max 500 caractères)
parent_idoptionnel	ID du commentaire auquel répondre (pour les réponses en fil)

Requête

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

Réponse 201

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

DELETE /comments/{comment} Authentification requise

Supprimer un commentaire que vous possédez.

Requête

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

Réponse 200

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

Utilisateurs

GET /users/{username}/posts Public

Obtenir les posts d'un utilisateur.

Requête

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

Réponse 200

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

GET /users/{username}/media Public

Obtenir les médias d'un utilisateur.

Requête

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

Réponse 200

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

GET /users/{username}/comments Public

Obtenir les commentaires d'un utilisateur (paginé).

Requête

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

GET /users/{username}/followers Public

Obtenir les abonnés d'un utilisateur (paginé).

Requête

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

GET /users/{username}/following Public

Obtenir les utilisateurs que cet utilisateur suit (paginé).

Requête

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

POST /users/{username}/follow Authentification requise

Suivre un utilisateur.

Requête

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

Réponse 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Authentification requise

Ne plus suivre un utilisateur.

Requête

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

Réponse 200

{
  "message": "User unfollowed."
}

Votes

POST /posts/{post}/upvote Authentification requise

Donner un vote positif à un post. Un nouvel appel supprime le vote positif.

Requête

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

Réponse 200

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

POST /posts/{post}/downvote Authentification requise

Donner un vote négatif à un post. Un nouvel appel supprime le vote négatif.

Requête

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

Réponse 200

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

POST /comments/{comment}/upvote Authentification requise

Donner un vote positif à un commentaire. Un nouvel appel supprime le vote positif.

Requête

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

POST /comments/{comment}/downvote Authentification requise

Donner un vote négatif à un commentaire. Un nouvel appel supprime le vote négatif.

Requête

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

URL d'images directes

Chaque fichier téléversé est servi via le CDN. La réponse média inclut un urls objet avec toutes les tailles 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)