imgpile API

Загружайте, делитесь и управляйте изображениями и видео программно.

https://imgpile.com/api/v1 — все endpoint'ы

https://cdn.imgpile.com/api/v1/media — только загрузка файлов (см. ниже)

Получите API-токен

Войти или зарегистрироваться чтобы сгенерировать API-токен.

Концепции

У imgpile есть два основных объекта. Понимание разницы сэкономит вам время.

Медиа

Один файл (изображение или видео). Имеет прямой URL CDN — идеально для хотлинкинга, встраивания или обмена.

Пост

Публикуемая страница, содержащая один или несколько элементов медиа. Имеет заголовок, описание, голосование, комментарии и теги.

Нужен только прямой URL изображения? Загрузить в /media. Используйте urls.original из ответа. Готово.

Хотите публикуемый пост с комментариями и голосованием? Сначала загрузите медиа, затем вызовите /posts с ID медиа.

Быстрый старт

Загрузите один файл и получите прямой URL CDN. Отлично подходит для ShareX, Discord-ботов или любого скрипта, которому просто нужно разместить изображение.

Примечание: загрузки отправляются в cdn.imgpile.com, не imgpile.com.

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

Ответ:

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

Загрузите несколько файлов, а затем сгруппируйте их в публикацию с метаданными, голосованием и комментариями.

1. Загружайте каждый файл в cdn.imgpile.com и сохраните возвращённый media ID:

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

2. Создайте публикацию с этими 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. (Необязательно) Добавьте заголовок и описание:

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

Ваша публикация уже доступна по адресу https://imgpile.com/p/xyz789

Загрузите изображение из браузера или 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

Настройка ShareX

Скачайте конфиг Custom Uploader и импортируйте его в ShareX — ручное редактирование JSON не требуется.

Скачать imgpile.sxcu

Нажмите кнопку выше, чтобы скачать imgpile.sxcu.
Дважды щёлкните по файлу — ShareX импортирует его и сделает imgpile доступным загрузчиком.
Открыть Назначения → Настройки пользовательского загрузчика → Заголовки и замените YOUR_TOKEN_HERE на ваш API-токен (сгенерируйте один в Введение).
Установить Назначения → Загрузчик изображений → imgpile. Сделайте скриншот — URL попадёт в буфер обмена как https://cdn.imgpile.com/f/….

Аутентификация

Эндпоинты для чтения (GET) — публичные и не требуют аутентификации. Все остальные endpoint'ы требуют bearer-токен.

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

Для аутентифицированных запросов передайте токен в Authorization заголовке:

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

Загрузка файлов на cdn.imgpile.com; см. Медиа → Загрузить для подробностей.

Сгенерируйте токен в Введение разделе выше.

Ошибки

API возвращает стандартные коды HTTP-статусов. В ответах об ошибках есть JSON-тело с полем message (или error) с описанием того, что пошло не так.

Коды статусов

Код	Значение
`200`	OK — запрос выполнен успешно
`201`	Created — ресурс создан
`400`	Bad Request — запрос сформирован неверно
`401`	Unauthenticated — токен отсутствует или недействителен
`403`	Запрещено — у вас нет прав на это действие
`404`	Не найдено — ресурс не существует
`422`	Validation failed — в теле запроса есть неверные поля
`429`	Rate Limited — слишком много запросов, замедлитесь
`451`	Unavailable for Legal Reasons — файл совпал с запрещённым хэшем
`500`	Server 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." }

Проверьте Retry-After заголовок ответа: сколько секунд осталось до сброса лимита.

451 Заблокированный контент

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

Пагинация API

Список endpoint'ов (GET /posts, GET /media) возвращать результаты с пагинацией. По умолчанию размер страницы 10; вы можете запросить до 250 с ?limit=N.

Используйте ?page=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
  }
}

При переборе следуйте links.next пока это null, или проверьте meta.current_page по meta.last_page.

Фильтрация контента

По умолчанию перечисление endpoint'ов (GET /posts, GET /media) возвращает только безопасный контент (статус модерации approved). Чтобы также включить взрослый контент (nsfw), пропустить ?nsfw=1:

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

Заблокированный контент (rejected, то есть спам или злоупотребления) никогда не возвращается в публичные feed endpoint'ы независимо от ?nsfw флага.

Каждый ответ по посту и медиа содержит moderation_status поле, чтобы вы могли предупреждать, размывать или скрывать отмеченные элементы в своём клиенте:

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

approved — безопасно для всех аудиторий.
pending — ожидает автоматической модерации.
nsfw — взрослый контент; возвращается из публичных endpoint'ов только когда ?nsfw=1.
rejected — спам/злоупотребления; никогда не возвращается в публичные endpoint'ы.

Скрытые посты доступны по slug, но никогда не появляются в лентах. Приватные посты требуют ?key=xxx параметр запроса (владелец может найти это в ссылке на шаринг поста).

Лимиты запросов

Публичные запросы (без токена): 30 запросов/минуту на IP
Аутентифицированные запросы: 120 запросов/минуту на пользователя
Загрузка файлов: 1 000 файлов/день на пользователя/IP
Максимальный размер файла: 100 МБ
Допустимые типы: image/* и video/*

Заголовки лимитов скорости включены в каждый ответ (X-RateLimit-Limit, X-RateLimit-Remaining).

Объект Media

Возвращается media endpoint'ами и встраивается в ответы по постам.

Поле	Тип	Описание
slug	`string`	Уникальный идентификатор из 7 символов. Используется в URL.
filename	`string`	Имя файла в хранилище (то же, что и slug).
title	`string\|null`	Заголовок, указанный пользователем.
description	`string\|null`	Описание, указанное пользователем.
type	`string`	MIME-тип — например `image/jpeg`, `video/mp4`.
width	`integer`	Ширина в пикселях.
height	`integer`	Высота в пикселях.
moderation_status	`enum`	Один из `approved`, `pending`, `nsfw`, или `rejected`. Смотреть Фильтрация контента.
processed	`boolean`	`false` пока генерируются варианты нужного размера; `true` когда будет готово.
created_at	`timestamp`	временная метка в формате ISO 8601.
urls	`object`	URL-адреса CDN для каждого доступного размера — см. Прямые URL изображений.
user	`object\|null`	Загрузчик (username, avatar). Для гостевых загрузок: null.

Объект Post

Общий контейнер для одного или нескольких медиа-объектов.

Поле	Тип	Описание
id	`integer`	Числовой ID. Используйте `slug` для URL-адресов.
slug	`string`	Уникальный идентификатор из 7 символов. Используется в URL.
title	`string\|null`	Заголовок поста.
description	`string\|null`	Описание поста.
score	`integer`	Итоговый рейтинг (апвоуты минус даунвоуты).
view_count	`integer`	Общее число просмотров страниц.
media_count	`integer`	Количество медиа-объектов в этом посте.
moderation_status	`enum`	Один из `approved`, `pending`, `nsfw`, или `rejected`. Смотреть Фильтрация контента.
isUpvotedByUser	`boolean`	Участвующий пользователь поставил этому посту апвоут.
isDownvotedByUser	`boolean`	Участвующий пользователь поставил этому посту даунвоут.
created_at	`timestamp`	временная метка в формате ISO 8601.
user	`object\|null`	Автор (username, avatar). Для гостевых постов: null.
media	`array`	Массив Медиа-объекты. Включается только в запросах одного поста.
first_media	`object\|null`	Первое медиа (превью). Включается только в ответы ленты.
Поля только для владельца (возвращаются только владельцу поста):
visibility	`enum`	`public`, `hidden`, или `private`.
access_key	`string\|null`	Требуется для просмотра приватного поста. Добавьте как `?key=xxx`.

Эндпоинты Media

Отдельные файлы (изображения или видео). У каждого медиа есть прямой URL на CDN, который можно использовать для hotlink или вставки где угодно.

POST /media Требуется авторизация

Хост загрузки

Отправлять загрузки на https://cdn.imgpile.com/api/v1/media — не imgpile.com. Файлы хранятся на выделенном origin; отправка POST на основной хост не сработает.

Все остальные эндпоинты используют imgpile.com/api/v1 как обычно.

Загрузите изображение или видео. Отправьте как multipart/form-data.

Параметр	Описание
fileобязательный	Файл для загрузки. Максимум 100 МБ. Поддерживаются image/* и video/*.
post_idнеобязательный	Прикрепить к существующему посту.

Запрос

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

Ответ 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 Публично

Список медиа-объектов с фильтрацией и пагинацией.

Параметр	Описание
tag	Фильтр по названию тега
sort	`latest` (по умолчанию) или `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Результатов на страницу (макс. 250, по умолчанию 10)
username	Фильтр по username
nsfw	Установите `1` чтобы включить контент NSFW. По умолчанию: только SFW.

Запрос

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

Ответ 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} Публично

Получить один медиа-объект по его slug.

Запрос

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

Ответ 200

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

PATCH /media/{slug} Требуется авторизация

Обновить медиа, которое принадлежит вам.

Параметр	Описание
title	Заголовок медиа
description	Описание медиа

Запрос

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

Ответ 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} Требуется авторизация

Удалить медиа, которое принадлежит вам.

Запрос

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

Ответ 200

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

Эндпоинты Post

Публичные страницы, которые содержат один или несколько медиа-объектов. У них есть заголовок, описание, голосование, комментарии и теги.

GET /posts Публично

Список публичных постов с фильтрацией и пагинацией.

Параметр	Описание
tag	Фильтр по названию тега
sort	`latest` (по умолчанию) или `random`
period	`day`, `week`, `month`, `year`, `all`
limit	Результатов на страницу (макс. 250, по умолчанию 10)
username	Фильтр по username
nsfw	Установите `1` чтобы включить контент NSFW. По умолчанию: только SFW.

Запрос

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

Ответ 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} Публично

Получить один пост с постраничными медиа.

Параметр	Описание
mediaPage	Номер страницы для медиа (по умолчанию 1)
perPage	Количество медиа на странице (по умолчанию 10)
key	Требуется для приватных постов. Владелец может найти это в ссылке для шаринга.

Запрос

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

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

Ответ 200

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

POST /posts Требуется авторизация

Создать новый пост из загруженных медиа.

Параметр	Описание
media_idsобязательный	Массив 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]}'

Ответ 201

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

PATCH /posts/{slug} Требуется авторизация

Обновить пост, который вы создали.

Параметр	Описание
title	Заголовок поста (макс. 255)
description	Описание поста
visibility	`public`, `hidden`, или `private`. Настройка для `private` автоматически генерирует `access_key`.
is_nsfw	Булево. Отметьте пост как контент для взрослых, чтобы он был скрыт за переключателем NSFW у зрителя. После установки пост не будет автоматически раскрыт ниже `nsfw`.
media_order	Массив slug'ов медиа в нужном порядке

Запрос

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

Ответ 200

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

DELETE /posts/{slug} Требуется авторизация

Удалить пост, который вы создали.

Запрос

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

Ответ 200

{
  "message": "Post deleted successfully"
}

Параметр	Описание
contentобязательный	Текст комментария (макс. 500 символов)
parent_idнеобязательный	ID комментария, на который нужно ответить (для ответов в ветке)

Пользователи

GET /users/{username}/posts Публично

Получить посты пользователя.

Запрос

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

Ответ 200

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

GET /users/{username}/media Публично

Получить медиа пользователя.

Запрос

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

Ответ 200

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

GET /users/{username}/comments Публично

Получить комментарии пользователя (постранично).

Запрос

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

GET /users/{username}/followers Публично

Получить подписчиков пользователя (постранично).

Запрос

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

GET /users/{username}/following Публично

Получить пользователей, за которыми следит этот пользователь (постранично).

Запрос

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

POST /users/{username}/follow Требуется авторизация

Подписаться на пользователя.

Запрос

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

Ответ 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow Требуется авторизация

Отписаться от пользователя.

Запрос

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

Ответ 200

{
  "message": "User unfollowed."
}

Голосование

POST /posts/{post}/upvote Требуется авторизация

Поставить лайк посту. Повторный вызов убирает лайк.

Запрос

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

Ответ 200

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

POST /posts/{post}/downvote Требуется авторизация

Поставить дизлайк посту. Повторный вызов убирает дизлайк.

Запрос

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

Ответ 200

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

POST /comments/{comment}/upvote Требуется авторизация

Поставить лайк комментарию. Повторный вызов убирает лайк.

Запрос

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

POST /comments/{comment}/downvote Требуется авторизация

Поставить дизлайк комментарию. Повторный вызов убирает дизлайк.

Запрос

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

Прямые URL изображений

Каждый загруженный файл отдаётся через CDN. В ответе на медиа есть urls объект со всеми доступными размерами:

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)

imgpile API

Получите API-токен

Концепции

Медиа

Пост

Быстрый старт

Настройка ShareX

Аутентификация

Ошибки

Коды статусов

Примеры ответов об ошибках

Пагинация API

Фильтрация контента

Лимиты запросов

Объект Media

Объект Post

Эндпоинты Media

Эндпоинты Post

Комментарии

Пользователи

Голосование

Прямые URL изображений