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

URL de Base: https://api.pichub.app/v1
Protocole: HTTPS Only
Format: JSON
Encodage: UTF-8

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

POST /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 控制图片是否在图片广场公开显示。可选值:1true = 公开(显示在广场),0false = 私密(不显示)。默认值:1(公开)

Essayer

Prend en charge les formats JPG, PNG, GIF, WebP, max 10 Mo

1 100
Résultat de la Réponse

                                                

                                                

Gestion des images

GET /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

                                                    

                                                    
DELETE /images/{id}

Supprimer l'image spécifiée

Avertissement

Cette action est irréversible et ne peut pas être annulée

Gestion des albums

POST /albums

Créer un nouvel album

Corps de la Requête

{
    "name": "我的相册",
    "description": "这是一个示例相册",
    "is_public": true
  }
GET /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
Copié dans le presse-papiers