Documentation API pour développeurs
API de stockage et de gestion d'images puissante et flexible. Intégration facile, développement rapide.
Fonctionnalités Principales
- Prise en charge du téléchargement d'images multi-format
- Traitement et mise à l'échelle dynamiques des images
- Gestion des albums et des catégories
- Notifications d'événements Webhook
Informations de Base
https://api.pichub.app/v1
Authentification
PicHub API 使用 Bearer 令牌进行身份认证。您需要在每个请求的 Authorization 头中包含有效的 API 密钥。
Obtenir Votre Clé API
Connexion requise pour utiliser cette fonctionnalité
Format de Requête
Authorization: Bearer YOUR_API_TOKEN
Traitement d'image dynamique
Utilisez la route /img/{path} pour le traitement et l'optimisation d'images en temps réel.
Paramètres URL
| Paramètre | Type | Description | Exemple |
|---|---|---|---|
| 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 |
Exemple d'Utilisation
https://cdn.pichub.app/{image_id}.webp?w=800&h=600&fit=crop&q=90
Limitation de débit
为确保 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 de téléchargement
/upload
Téléchargez des images sur PicHub. Prend en charge plusieurs formats d'image avec optimisation et traitement automatiques.
Paramètres
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| files[] | file array | Oui | Fichiers image à télécharger (prend en charge plusieurs fichiers) |
| album_id | integer | Non | ID d'album optionnel pour ajouter des images à un album spécifique |
| quality | integer | Non | Qualité de compression d'image, plage 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(公开)
|
Essayer
Prend en charge les formats JPG, PNG, GIF, WebP, max 10 Mo
Résultat de la Réponse
Gestion des images
/images
Obtenir la liste des images de l'utilisateur avec pagination et filtrage par album
Paramètres de Requête
| Paramètre | Type | Par Défaut | Description |
|---|---|---|---|
| page | integer | 1 | Numéro de Page |
| per_page | integer | 20 | Par Page |
| album_id | string | - | Filtrer par Album |
Essayer
Résultat de la Réponse
/images/{id}
Supprimer l'image spécifiée
Avertissement
Cette action est irréversible et ne peut pas être annulée
Gestion des albums
/albums
Créer un nouvel album
Corps de la Requête
{
"name": "我的相册",
"description": "这是一个示例相册",
"is_public": true
}
/albums
Obtenir la liste des albums de l'utilisateur
Webhooks
PicHub prend en charge les notifications d'événements Webhook. Des requêtes POST seront envoyées à votre URL configurée lorsque des événements spécifiques se produisent.
Événements Pris en Charge
image.uploaded
Image Téléchargée
image.deleted
Image Supprimée
album.created
Album Créé
album.updated
Album Mis à Jour
Codes d'erreur
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."
}
}
Exemples de code
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