imgpile API

프로그래밍으로 이미지와 동영상을 업로드하고 공유하며 관리하세요.

https://imgpile.com/api/v1 — 모든 엔드포인트

https://cdn.imgpile.com/api/v1/media — 파일 업로드만 가능 (참조: 아래)

API 토큰 받기

로그인 또는 회원가입 을(를) 통해 API 토큰을 생성하세요.

개념

imgpile에는 두 가지 핵심 객체가 있습니다. 차이를 이해하면 시간을 절약할 수 있어요.

미디어

단일 파일(이미지 또는 동영상)입니다. 직접 CDN URL이 있어 핫링크, 임베딩 또는 공유에 이상적이에요.

게시물

하나 이상의 미디어 항목을 담아 공유할 수 있는 페이지입니다. 제목, 설명, 투표, 댓글, 태그가 있어요.

직접 이미지 URL만 필요하신가요? 업로드 대상 /media. 사용 urls.original 응답에서 가져오세요. 끝!

댓글과 투표가 포함된 공유용 게시물을 원하시나요? 먼저 미디어를 업로드한 다음 /posts 미디어 ID로 호출하세요.

빠른 시작

파일 하나를 업로드하고 바로 CDN URL을 받으세요. 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 에 업로드하고, 반환된 미디어 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 설정

커스텀 업로더 설정 파일을 다운로드한 뒤 ShareX에 가져오세요. 수동 JSON 편집은 필요 없어요.

imgpile.sxcu 다운로드

위 버튼을 눌러 다운로드 imgpile.sxcu.
파일을 두 번 클릭하세요. ShareX가 가져와서 imgpile 사용 가능한 업로더를 만들어줍니다.
열기 대상 → 사용자 지정 업로더 설정 → 헤더 그리고 YOUR_TOKEN_HERE 를 API 토큰으로 바꾸세요(아래의 소개).
설정 대상 → 이미지 업로더 → imgpile. 스크린샷을 캡처하세요. URL이 클립보드에 https://cdn.imgpile.com/f/….

인증

읽기 엔드포인트(GET)는 공개 인증이 필요하지 않습니다. 그 외 모든 엔드포인트는 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 상태 코드를 반환합니다. 오류 응답에는 어떤 문제가 있었는지 설명하는 message (또는 error) 필드가 포함된 JSON 본문이 들어있습니다.

상태 코드

코드	의미
`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 페이징

엔드포인트 나열 (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.

콘텐츠 필터링

기본적으로 엔드포인트를 나열하면 (GET /posts, GET /media) 안전한 콘텐츠만 반환합니다(검토 상태 approved). 성인 콘텐츠도 포함하려면 (nsfw), 통과 ?nsfw=1:

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

차단된 콘텐츠 (rejected, 즉, 스팸 또는 악용은 어떤 경우에도 공개 피드 엔드포인트로 절대 반환되지 않습니다. 이는 ?nsfw 플래그와 무관합니다.

모든 게시물 및 미디어 응답에는 moderation_status 필드가 포함되어, 클라이언트에서 신고된 항목을 경고/블러/숨김 처리할 수 있습니다:

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

approved — 모든 사용자에게 안전합니다.
pending — 자동 검토가 대기 중입니다.
nsfw — 성인 콘텐츠입니다. 다음 조건일 때만 공개 엔드포인트에서 반환됩니다. ?nsfw=1.
rejected — 스팸/악용입니다. 공개 엔드포인트로는 절대 반환되지 않습니다.

숨김 게시물 슬러그로는 접근할 수 있지만 피드에는 절대 표시되지 않습니다. 비공개 게시물 다음이 필요합니다: ?key=xxx 쿼리 파라미터 (소유자는 게시물의 공유 링크에서 이 값을 확인할 수 있습니다).

요청 제한

공개 요청 (토큰 없음): IP당 분당 30회 요청
인증된 요청: 사용자당 분당 120회 요청
파일 업로드: 사용자/IP당 하루 1,000개 파일
최대 파일 크기: 100 MB
허용되는 형식: image/* 및 video/*

요청 제한(Rate limit) 헤더는 모든 응답에 포함됩니다 (X-RateLimit-Limit, X-RateLimit-Remaining).

미디어 객체

미디어 엔드포인트에서 반환되며 게시물 응답 안에 포함됩니다.

필드	유형	설명
slug	`string`	고유한 7자리 식별자입니다. URL에 사용됩니다.
filename	`string`	저장 파일명(슬러그와 동일).
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`	사용 가능한 모든 크기의 CDN URL — 다음을 확인하세요 직접 이미지 URL.
user	`object\|null`	업로더(사용자 이름, 아바타). 게스트 업로드의 경우 null.

게시물 객체

하나 이상의 미디어 항목을 담아 공유할 수 있는 컨테이너.

필드	유형	설명
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`	작성자(사용자 이름, 아바타). 게스트 게시물의 경우 null.
media	`array`	다음의 배열 미디어 객체. 단일 게시물 요청에서만 포함됩니다.
first_media	`object\|null`	첫 번째 미디어(미리보기). 피드 응답에서만 포함됩니다.
소유자 전용 필드 (게시물 소유자에게만 반환됨):
visibility	`enum`	`public`, `hidden`, 또는 `private`.
access_key	`string\|null`	비공개 게시물을 보려면 필요합니다. 다음처럼 덧붙이세요 `?key=xxx`.

미디어 엔드포인트

개별 파일(이미지 또는 동영상). 각 미디어는 어디서든 핫링크하거나 임베드할 수 있는 직접 CDN URL을 가집니다.

POST /media 인증 필요

업로드 호스트

업로드를 다음으로 전송 https://cdn.imgpile.com/api/v1/media — 아니요 imgpile.com. 파일은 전용 오리진에 저장됩니다. 메인 호스트로 POST하면 실패합니다.

그 외 모든 엔드포인트는 imgpile.com/api/v1 평소처럼.

이미지 또는 동영상을 업로드하세요. 다음 형식으로 전송 multipart/form-data.

매개변수	설명
file필수	업로드할 파일. 최대 100MB. 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	사용자 이름으로 필터링
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} 공개

슬러그로 단일 미디어 항목을 가져옵니다.

요청

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

게시물 엔드포인트

하나 이상의 미디어 항목을 담는 공유용 페이지입니다. 제목, 설명, 투표, 댓글, 태그를 가집니다.

GET /posts 공개

필터링과 페이징을 통해 공개 게시물을 나열합니다.

매개변수	설명
tag	태그 이름으로 필터링
sort	`latest` (기본값) 또는 `random`
period	`day`, `week`, `month`, `year`, `all`
limit	페이지당 결과 수(최대 250, 기본값 10)
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	원하는 순서대로 정렬한 미디어 슬러그 배열

요청

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

POST /posts/{post}/comments 인증 필요

게시물에 댓글을 추가합니다.

매개변수	설명
content필수	댓글 내용 (최대 500자)
parent_id선택	대댓글로 달 댓글 ID (스레드형 답글용)

요청

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

응답 201

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

DELETE /comments/{comment} 인증 필요

내가 소유한 댓글을 삭제합니다.

요청

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

응답 200

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

사용자

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)