Developer API Documentation
Powerful and flexible image storage and management API. Easy integration, rapid development.
Core Features
- Multi-format image upload support
- Dynamic image processing and scaling
- Album and category management
- Webhook event notifications
Basic Information
https://api.pichub.app/v1
Authentication
PicHub API 使用 Bearer 令牌进行身份认证。您需要在每个请求的 Authorization 头中包含有效的 API 密钥。
Get Your API Key
Login required to use this feature
Request Format
Authorization: Bearer YOUR_API_TOKEN
Dynamic Image Processing
Use the /img/{path} route for real-time image processing and optimization.
URL Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| w | integer | 图片宽度(像素) | w=300 |
| h | integer | 图片高度(像素) | h=200 |
| q | integer | 压缩质量 (1-100) | q=85 |
| fit | string | 缩放模式:cover, contain, fill, inside, outside | fit=cover |
| fm | string | 输出格式:jpg, png, webp, avif | fm=webp |
Usage Example
https://cdn.pichub.app/{image_id}.webp?w=800&h=600&fit=crop&q=90
Rate Limiting
为确保 API 服务的稳定性和公平性,我们对所有 API 请求实施了速率限制。
API 请求限制
- 每分钟:60 次请求
- 每小时:1,000 次请求
- 每天:10,000 次请求
上传限制
- 每分钟:10 次上传
- 单文件大小:最大 50MB
- 支持格式:JPG, PNG, WebP, GIF
响应头信息
| 响应头 | 说明 | 示例 |
|---|---|---|
| X-RateLimit-Limit | 当前时间窗口内的请求限制 | 60 |
| X-RateLimit-Remaining | 当前时间窗口内剩余请求次数 | 45 |
| X-RateLimit-Reset | 速率限制重置时间(Unix 时间戳) | 1640995200 |
Upload API
/upload
Upload images to PicHub. Supports multiple image formats with automatic optimization and processing.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| files[] | file array | Yes | Image files to upload (supports multiple files) |
| album_id | integer | No | Optional album ID to add images to a specific album |
| quality | integer | No | Image compression quality, range 1-100 |
| format | string | 否 | 输出格式。可选值:auto,
jpeg,
png,
webp。默认:auto
|
| remove_exif | boolean | 否 | 移除图片 EXIF 信息。可选值:true,
false,
0,
1。默认:false
|
| convertToWebP | boolean | 否 | 转换为 WebP 格式(更小的文件大小)。可选值:true,
false,
0,
1。默认:true
|
| auto_rename | boolean | 否 | 自动生成随机文件名。可选值:true,
false,
0,
1。默认:false
|
| is_public | boolean | 否 | 控制图片是否在图片广场公开显示。可选值:1
或 true
= 公开(显示在广场),0
或 false
= 私密(不显示)。默认值:1(公开)
|
Try It Out
Supports JPG, PNG, GIF, WebP formats, max 10MB
Response Result
Image Management
/images
Get user's image list with pagination and album filtering support
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | integer | 1 | Page Number |
| per_page | integer | 20 | Per Page |
| album_id | string | - | Filter by Album |
Try It Out
Response Result
/images/{id}
Delete specified image
Warning
This action is irreversible and cannot be undone
Album Management
/albums
Create new album
Request Body
{
"name": "我的相册",
"description": "这是一个示例相册",
"is_public": true
}
/albums
Get user's album list
Webhooks
PicHub supports Webhook event notifications. POST requests will be sent to your configured URL when specific events occur.
Supported Events
image.uploaded
Image Uploaded
image.deleted
Image Deleted
album.created
Album Created
album.updated
Album Updated
Error Codes
PicHub API 使用标准的 HTTP 状态码来表示请求成功或失败。所有错误响应都包含详细的错误信息。
| HTTP 状态码 | 错误代码 | 说明 |
|---|---|---|
| 400 | BAD_REQUEST | 请求参数错误 |
| 401 | UNAUTHORIZED | 认证失败或令牌无效 |
| 403 | FORBIDDEN | 权限不足 |
| 404 | NOT_FOUND | 资源不存在 |
| 413 | PAYLOAD_TOO_LARGE | 文件大小超过50MB限制 |
| 415 | UNSUPPORTED_MEDIA_TYPE | 不支持的文件格式 |
| 422 | VALIDATION_ERROR | 请求数据验证失败 |
| 429 | RATE_LIMIT_EXCEEDED | 请求频率超限 |
| 507 | INSUFFICIENT_STORAGE | 存储空间不足 |
错误响应示例
认证失败 (401):
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired API token",
"details": "Please check your API token and ensure it has not expired"
}
}
文件过大 (413):
{
"success": false,
"error": {
"code": "PAYLOAD_TOO_LARGE",
"message": "File size exceeds maximum limit",
"details": "Maximum file size is 50MB. Your file is 75MB."
}
}
Code Examples
JavaScript
// 上传图片示例(支持多文件上传)
async function uploadImage(files, albumId, isPublic = true) {
const formData = new FormData();
// 支持多文件上传
if (Array.isArray(files)) {
files.forEach(file => formData.append('files[]', file));
} else {
formData.append('files[]', files);
}
if (albumId) formData.append('album_id', albumId);
formData.append('quality', 85);
formData.append('is_public', isPublic ? '1' : '0'); // 控制是否在图片广场显示
try {
const response = await fetch('https://api.pichub.app/api/v1/upload', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
},
body: formData
});
const result = await response.json();
if (result.success) {
console.log('上传成功:', result.data);
return result.data;
} else {
throw new Error(result.message);
}
} catch (error) {
console.error('上传失败:', error.message);
throw error;
}
}
Python
import requests
def upload_image(file_path, album_id, description, api_token):
url = "https://api.pichub.app/api/v1/upload"
headers = {
"Authorization": f"Bearer {api_token}"
}
data = {
"album_id": album_id,
"description": description
}
try:
with open(file_path, 'rb') as f:
files = {'image': f}
response = requests.post(url, headers=headers, files=files, data=data)
response.raise_for_status()
result = response.json()
if result['success']:
print('上传成功:', result['data'])
return result['data']
else:
raise Exception(result['message'])
except requests.exceptions.HTTPError as err:
error_data = err.response.json()
print(f"HTTP 错误: {error_data['message']}")
raise
except Exception as err:
print(f"上传失败: {err}")
raise