imgpile API

通过代码上传、分享和管理图片与视频。

https://imgpile.com/api/v1 — 所有端点

https://cdn.imgpile.com/api/v1/media — 仅文件上传（见下方)

获取 API 令牌

登录或注册以生成 API 令牌。

概念

imgpile 有两个核心对象。了解它们的区别会帮你节省时间。

媒体

单个文件（图片或视频）。有一个直接的 CDN 链接——非常适合热链、嵌入或分享。

帖子

一个可分享的页面，包含一个或多个媒体条目。包含标题、描述、投票、评论和标签。

只需要一个直接图片链接？ 上传到 /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 一个可用的上传器。
打开 目标 → 自定义上传器设置 → Headers 并替换 YOUR_TOKEN_HERE 为你的 API 令牌（在简介).
设置 目标 → 图片上传器 → imgpile. 截取屏幕截图——URL 将以 https://cdn.imgpile.com/f/….

身份验证

读取端点（GET）是公开并且不需要身份验证。其他所有端点都需要 bearer token。

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；你可以使用 ?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 标记为何，均不会返回到公开的动态/Feed 端点。

每个帖子和媒体响应都包含一个 moderation_status 字段，方便你在客户端中对被标记的内容进行警告、模糊或隐藏：

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

approved — 对所有受众都安全。
pending — 等待自动审核。
nsfw — 成人内容；仅在以下条件满足时才会从公开端点返回 ?nsfw=1.
rejected — 垃圾信息/滥用；从不返回到公开端点。

隐藏的帖子 可通过其 slug 访问，但从不出现在动态/Feed 中。 私有帖子 需要一个 ?key=xxx 查询参数（所有者可以在帖子的分享链接中找到它）。

速率限制

公开请求 （无令牌）：每个 IP 每分钟 30 次请求
已认证请求: 每个用户每分钟 120 次请求
文件上传: 每个用户/IP 每天 1,000 个文件
最大文件大小: 100 MB
接受的类型: image/* 和 video/*

速率限制（Rate limit）头会包含在每个响应中 (X-RateLimit-Limit, X-RateLimit-Remaining).

Media 对象

由媒体端点返回，并嵌入到帖子响应中。

字段	类型	描述
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`	每个可用尺寸的 CDN URL — 见直接图片链接.
user	`object\|null`	上传者（用户名、头像）。游客上传则为 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`	作者（用户名、头像）。游客帖子则为 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必填	要上传的文件。最大 100 MB。支持 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} 公开

通过 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	按指定顺序排列的媒体 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"
}

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"

直接图片链接

每个上传的文件都会通过 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)