imgpile API

Przesyłaj, udostępniaj i zarządzaj obrazami oraz filmami programowo.

https://imgpile.com/api/v1 — wszystkie endpointy

https://cdn.imgpile.com/api/v1/media — tylko przesyłanie plików (zobacz poniżej)

Pobierz token API

Zaloguj się lub zarejestruj się aby wygenerować token API.

Koncepcje

imgpile ma dwa podstawowe obiekty. Zrozumienie różnicy oszczędzi Ci czas.

Media

Pojedynczy plik (obraz lub wideo). Ma bezpośredni adres URL CDN — idealny do hotlinkowania, osadzania lub udostępniania.

Post

Udostępnialna strona zawierająca jeden lub więcej elementów multimedialnych. Ma tytuł, opis, głosowanie, komentarze i tagi.

Potrzebujesz tylko bezpośredniego adresu URL obrazu? Prześlij do /media. Użyj urls.original z odpowiedzi. Gotowe.

Chcesz udostępnialny post z komentarzami i głosowaniem? Najpierw prześlij media, a potem wywołaj /posts z identyfikatorami mediów.

Szybki start

Wgraj pojedynczy plik i uzyskaj bezpośredni adres URL CDN. Idealne dla ShareX, botów Discorda lub każdego skryptu, który po prostu musi hostować obraz.

Uwaga: przesyłane pliki trafiają do cdn.imgpile.com, nie imgpile.com.

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

Odpowiedź:

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

Wgraj wiele plików, a potem zgrupuj je w poście wraz z metadanymi, głosowaniem i komentarzami.

1. Wgraj każdy plik do cdn.imgpile.com i zapisz zwrócony identyfikator media:

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

2. Utwórz post z tymi identyfikatorami:

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. (Opcjonalnie) Dodaj tytuł i opis:

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

Twój post jest już aktywny pod adresem https://imgpile.com/p/xyz789

Wgraj obraz z przeglądarki lub 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

Konfiguracja ShareX

Pobierz naszą konfigurację Custom Uploader i zaimportuj ją do ShareX — nie trzeba ręcznie edytować JSON.

Pobierz imgpile.sxcu

Kliknij przycisk powyżej, aby pobrać imgpile.sxcu.
Dwukrotnie kliknij plik — ShareX zaimportuje go i utworzy imgpile dostępny uploader.
Otwórz Miejsca docelowe → Ustawienia niestandardowego uploadera → Nagłówki i zamień YOUR_TOKEN_HERE na swój token API (wygeneruj go w sekcji Wprowadzenie).
Ustaw Miejsca docelowe → Uploader obrazów → imgpile. Zrób zrzut ekranu — adres URL trafi do schowka jako https://cdn.imgpile.com/f/….

Uwierzytelnianie

Odczyt endpointów (GET) jest publiczny i nie wymagają uwierzytelniania. Wszystkie pozostałe endpointy wymagają tokena typu bearer.

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

Dla żądań uwierzytelnionych przekaż swój token w Authorization nagłówku:

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

Docelowe przesyłanie plików cdn.imgpile.com; zobacz Media → Prześlij aby uzyskać szczegóły.

Wygeneruj token w Wprowadzenie sekcji powyżej.

Błędy

API zwraca standardowe kody statusu HTTP. Odpowiedzi błędów zawierają treść JSON z polem message (lub error) opisującym, co poszło nie tak.

Kody statusu

Kod	Znaczenie
`200`	OK — żądanie powiodło się
`201`	Created — zasób został utworzony
`400`	Bad Request — niepoprawnie sformułowane żądanie
`401`	Unauthenticated — brak lub nieprawidłowy token
`403`	Zabronione — nie masz uprawnień do wykonania tej akcji
`404`	Nie znaleziono — zasób nie istnieje
`422`	Validation failed — treść żądania ma nieprawidłowe pola
`429`	Rate Limited — zbyt wiele żądań, zwolnij
`451`	Unavailable for Legal Reasons — plik pasował do zablokowanego hasha
`500`	Server Error — coś poszło nie tak po naszej stronie

Przykładowe odpowiedzi błędów

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

Sprawdź Retry-After nagłówek odpowiedzi pod kątem liczby sekund do zresetowania limitu.

451 Zablokowana treść

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

Stronicowanie API

Wyświetl punkty końcowe (GET /posts, GET /media) zwracają wyniki stronicowane. Domyślny rozmiar strony to 10; możesz poprosić o maksymalnie 250 za pomocą ?limit=N.

Użyj ?page=N do nawigacji po stronach. Odpowiedź zawiera metadane stronicowania:

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

Podczas iterowania postępuj zgodnie z links.next dopóki null, lub sprawdź meta.current_page względem meta.last_page.

Filtrowanie treści

Domyślnie punkty końcowe wyświetlania (GET /posts, GET /media) zwracają tylko bezpieczną treść (status moderacji approved). Aby uwzględnić także treści dla dorosłych (nsfw), przekaż ?nsfw=1:

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

Zablokowana treść (rejected, tj. spam lub nadużycia) nigdy nie jest zwracane do publicznych punktów feedu niezależnie od ?nsfw flagi.

Każda odpowiedź dla posta i multimediów zawiera moderation_status pole, dzięki któremu możesz ostrzegać, rozmywać lub ukrywać oznaczone elementy w swoim kliencie:

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

approved — bezpieczne dla wszystkich odbiorców.
pending — oczekuje na automatyczną moderację.
nsfw — treści dla dorosłych; zwracane z publicznych punktów końcowych tylko gdy ?nsfw=1.
rejected — spam/nadużycia; nigdy nie są zwracane do publicznych punktów końcowych.

Ukryte posty są dostępne po ich slug, ale nigdy nie pojawiają się w feedach. Prywatne posty wymagają ?key=xxx parametr zapytania (właściciel może to znaleźć w linku do udostępnienia wpisu).

Limity zapytań

Żądania publiczne (bez tokenu): 30 żądań/minutę na adres IP
Żądania uwierzytelnione: 120 żądań/minutę na użytkownika
Przesyłanie plików: 1 000 plików/dzień na użytkownika/adres IP
Maksymalny rozmiar pliku: 100 MB
Akceptowane typy: image/* i video/*

Nagłówki limitu zapytań są dołączane do każdej odpowiedzi (X-RateLimit-Limit, X-RateLimit-Remaining).

Obiekt Media

Zwracane przez punkty końcowe multimediów i osadzane w odpowiedziach dla postów.

Pole	Typ	Opis
slug	`string`	Unikalny identyfikator o długości 7 znaków. Używany w adresach URL.
filename	`string`	Nazwa pliku w magazynie (taka sama jak slug).
title	`string\|null`	Tytuł podany przez użytkownika.
description	`string\|null`	Opis podany przez użytkownika.
type	`string`	Typ MIME — np. `image/jpeg`, `video/mp4`.
width	`integer`	Szerokość w pikselach.
height	`integer`	Wysokość w pikselach.
moderation_status	`enum`	Jedno z `approved`, `pending`, `nsfw`, lub `rejected`. Zobacz Filtrowanie treści.
processed	`boolean`	`false` podczas generowania wariantów o różnych rozmiarach; `true` gdy będzie gotowe.
created_at	`timestamp`	znacznik czasu w formacie ISO 8601.
urls	`object`	adresy URL CDN we wszystkich dostępnych rozmiarach — zobacz Bezpośrednie adresy URL obrazów.
user	`object\|null`	Nadawca (username, avatar). Dla gości: null.

Obiekt Post

Udostępniany kontener dla jednego lub więcej elementów multimedialnych.

Pole	Typ	Opis
id	`integer`	Numeryczny identyfikator. Użyj `slug` do adresów URL.
slug	`string`	Unikalny identyfikator o długości 7 znaków. Używany w adresach URL.
title	`string\|null`	Tytuł posta.
description	`string\|null`	Opis posta.
score	`integer`	Wynik głosowania netto (głosy za minus głosy przeciw).
view_count	`integer`	Łączna liczba wyświetleń strony.
media_count	`integer`	Liczba elementów multimedialnych w tym poście.
moderation_status	`enum`	Jedno z `approved`, `pending`, `nsfw`, lub `rejected`. Zobacz Filtrowanie treści.
isUpvotedByUser	`boolean`	Czy uwierzytelniony użytkownik oddał głos za na ten post.
isDownvotedByUser	`boolean`	Czy uwierzytelniony użytkownik oddał głos przeciw na ten post.
created_at	`timestamp`	znacznik czasu w formacie ISO 8601.
user	`object\|null`	Autor (username, avatar). Dla gości: null.
media	`array`	Tablica Obiekty multimedialne. Uwzględniane tylko w zapytaniach o pojedynczy post.
first_media	`object\|null`	Pierwsze media (podgląd). Uwzględniane tylko w odpowiedziach z feedu.
Pola dostępne tylko dla właściciela (zwracane wyłącznie właścicielowi wpisu):
visibility	`enum`	`public`, `hidden`, lub `private`.
access_key	`string\|null`	Wymagane do obejrzenia prywatnego posta. Dodaj jako `?key=xxx`.

Endpointy dla mediów

Pojedyncze pliki (obrazy lub wideo). Każde media ma bezpośredni adres URL do CDN, którego możesz użyć jako hotlink lub osadzić gdziekolwiek.

POST /media Wymagane uwierzytelnienie

Host do przesyłania

Wysyłaj przesyłane pliki do https://cdn.imgpile.com/api/v1/media — nie imgpile.com. Pliki są przechowywane na dedykowanym originie; wysyłanie POST na główny host nie zadziała.

Pozostałe endpointy używają imgpile.com/api/v1 jak zwykle.

Prześlij obraz lub wideo. Wyślij jako multipart/form-data.

Parametr	Opis
filewymagany	Plik do przesłania. Maks. 100 MB. Akceptuje image/* i video/*.
post_idopcjonalny	Dołącz do istniejącego posta.

Żądanie

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

Odpowiedź 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 Publiczne

Lista elementów multimedialnych z filtrowaniem i stronicowaniem.

Parametr	Opis
tag	Filtruj po nazwie tagu
sort	`latest` (domyślnie) lub `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Wyników na stronę (max 250, domyślnie 10)
username	Filtruj po nazwie użytkownika
nsfw	Ustaw na `1` aby uwzględnić treści NSFW. Domyślnie: tylko SFW.

Żądanie

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

Odpowiedź 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} Publiczne

Pobierz pojedyncze media po slug.

Żądanie

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

Odpowiedź 200

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

PATCH /media/{slug} Wymagane uwierzytelnienie

Aktualizuj media, które posiadasz.

Parametr	Opis
title	Tytuł mediów
description	Opis mediów

Żądanie

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

Odpowiedź 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Wymagane uwierzytelnienie

Usuń media, które posiadasz.

Żądanie

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

Odpowiedź 200

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

Endpointy dla postów

Udostępniane strony zawierające jeden lub więcej elementów multimedialnych. Mają tytuł, opis, głosowanie, komentarze i tagi.

GET /posts Publiczne

Lista publicznych postów z filtrowaniem i stronicowaniem.

Parametr	Opis
tag	Filtruj po nazwie tagu
sort	`latest` (domyślnie) lub `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Wyników na stronę (max 250, domyślnie 10)
username	Filtruj po nazwie użytkownika
nsfw	Ustaw na `1` aby uwzględnić treści NSFW. Domyślnie: tylko SFW.

Żądanie

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

Odpowiedź 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} Publiczne

Pobierz pojedynczy wpis z mediami stronicowanymi.

Parametr	Opis
mediaPage	Numer strony dla mediów (domyślnie 1)
perPage	Liczba elementów mediów na stronę (domyślnie 10)
key	Wymagane dla prywatnych wpisów. Właściciel może to znaleźć w linku do udostępnienia.

Żądanie

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

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

Odpowiedź 200

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

POST /posts Wymagane uwierzytelnienie

Utwórz nowy wpis na podstawie przesłanych mediów.

Parametr	Opis
media_idswymagany	Tablica identyfikatorów mediów do uwzględnienia we wpisie

Żądanie

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

Odpowiedź 201

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

PATCH /posts/{slug} Wymagane uwierzytelnienie

Zaktualizuj wpis, którego jesteś właścicielem.

Parametr	Opis
title	Tytuł wpisu (maks. 255)
description	Opis wpisu
visibility	`public`, `hidden`, lub `private`. Ustawienie dla `private` automatycznie generuje `access_key`.
is_nsfw	Wartość logiczna. Oznacz wpis jako treść dla dorosłych, aby był ukryty za przełącznikiem NSFW u widza. Po ustawieniu wpis nie będzie automatycznie rozwiązywany poniżej `nsfw`.
media_order	Tablica slugów mediów w żądanej kolejności

Żądanie

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

Odpowiedź 200

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

DELETE /posts/{slug} Wymagane uwierzytelnienie

Usuń wpis, którego jesteś właścicielem.

Żądanie

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

Odpowiedź 200

{
  "message": "Post deleted successfully"
}

Komentarze

POST /posts/{post}/comments Wymagane uwierzytelnienie

Dodaj komentarz do wpisu.

Parametr	Opis
contentwymagany	Treść komentarza (maks. 500 znaków)
parent_idopcjonalny	ID komentarza, na który odpowiedzieć (dla odpowiedzi w wątku)

Żądanie

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

Odpowiedź 201

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

DELETE /comments/{comment} Wymagane uwierzytelnienie

Usuń komentarz, którego jesteś właścicielem.

Żądanie

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

Odpowiedź 200

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

Użytkownicy

GET /users/{username}/posts Publiczne

Pobierz wpisy użytkownika.

Żądanie

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

Odpowiedź 200

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

GET /users/{username}/media Publiczne

Pobierz media użytkownika.

Żądanie

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

Odpowiedź 200

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

GET /users/{username}/comments Publiczne

Pobierz komentarze użytkownika (stronicowane).

Żądanie

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

GET /users/{username}/followers Publiczne

Pobierz obserwujących użytkownika (stronicowane).

Żądanie

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

GET /users/{username}/following Publiczne

Pobierz użytkowników, których ten użytkownik obserwuje (stronicowane).

Żądanie

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

POST /users/{username}/follow Wymagane uwierzytelnienie

Obserwuj użytkownika.

Żądanie

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

Odpowiedź 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Wymagane uwierzytelnienie

Przestań obserwować użytkownika.

Żądanie

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

Odpowiedź 200

{
  "message": "User unfollowed."
}

Głosowanie

POST /posts/{post}/upvote Wymagane uwierzytelnienie

Dodaj głos pozytywny do wpisu. Ponowne wywołanie usuwa głos.

Żądanie

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

Odpowiedź 200

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

POST /posts/{post}/downvote Wymagane uwierzytelnienie

Dodaj głos negatywny do wpisu. Ponowne wywołanie usuwa głos.

Żądanie

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

Odpowiedź 200

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

POST /comments/{comment}/upvote Wymagane uwierzytelnienie

Dodaj głos pozytywny do komentarza. Ponowne wywołanie usuwa głos.

Żądanie

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

POST /comments/{comment}/downvote Wymagane uwierzytelnienie

Dodaj głos negatywny do komentarza. Ponowne wywołanie usuwa głos.

Żądanie

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

Bezpośrednie adresy URL obrazów

Każdy przesłany plik jest udostępniany przez CDN. Odpowiedź dla mediów zawiera urls obiekt ze wszystkimi dostępnymi rozmiarami:

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)