Документация API для разработчиков
Мощный и гибкий API для хранения и управления изображениями. Простая интеграция, быстрая разработка.
Основные Функции
- Поддержка загрузки изображений в нескольких форматах
- Динамическая обработка и масштабирование изображений
- Управление альбомами и категориями
- Уведомления о событиях Webhook
Основная Информация
https://api.pichub.app/v1
Аутентификация
PicHub API 使用 Bearer 令牌进行身份认证。您需要在每个请求的 Authorization 头中包含有效的 API 密钥。
Получить Ваш API Ключ
Требуется вход для использования этой функции
Формат Запроса
Authorization: Bearer YOUR_API_TOKEN
Динамическая обработка изображений
Используйте маршрут /img/{path} для обработки и оптимизации изображений в реальном времени.
Параметры URL
| Параметр | Тип | Описание | Пример |
|---|---|---|---|
| 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 |
Пример Использования
https://cdn.pichub.app/{image_id}.webp?w=800&h=600&fit=crop&q=90
Ограничение скорости
为确保 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 |
API загрузки
/upload
Загрузите изображения в PicHub. Поддерживает несколько форматов изображений с автоматической оптимизацией и обработкой.
Параметры
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| files[] | file array | Да | Файлы изображений для загрузки (поддерживает несколько файлов) |
| album_id | integer | Нет | Необязательный ID альбома для добавления изображений в конкретный альбом |
| quality | integer | Нет | Качество сжатия изображения, диапазон 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(公开)
|
Попробовать
Поддерживает форматы JPG, PNG, GIF, WebP, макс. 10 МБ
Результат Ответа
Управление изображениями
/images
Получить список изображений пользователя с поддержкой пагинации и фильтрации по альбомам
Параметры Запроса
| Параметр | Тип | По Умолчанию | Описание |
|---|---|---|---|
| page | integer | 1 | Номер Страницы |
| per_page | integer | 20 | На Странице |
| album_id | string | - | Фильтр по Альбому |
Попробовать
Результат Ответа
/images/{id}
Удалить указанное изображение
Предупреждение
Это действие необратимо и не может быть отменено
Управление альбомами
/albums
Создать новый альбом
Тело Запроса
{
"name": "我的相册",
"description": "这是一个示例相册",
"is_public": true
}
/albums
Получить список альбомов пользователя
Webhooks
PicHub поддерживает уведомления о событиях Webhook. POST-запросы будут отправлены на ваш настроенный URL при возникновении определенных событий.
Поддерживаемые События
image.uploaded
Изображение Загружено
image.deleted
Изображение Удалено
album.created
Альбом Создан
album.updated
Альбом Обновлен
Коды ошибок
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."
}
}
Примеры кода
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