Core Features

  • Multi-format image upload support
  • Dynamic image processing and scaling
  • Album and category management
  • Webhook event notifications

Basic Information

Base URL: https://api.pichub.app/v1
Protocol: HTTPS Only
Format: JSON
Encoding: UTF-8

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

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

Try It Out

Supports JPG, PNG, GIF, WebP formats, max 10MB

1 100
Response Result

                                                

                                                

Image Management

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

                                                    

                                                    
DELETE /images/{id}

Delete specified image

Warning

This action is irreversible and cannot be undone

Album Management

POST /albums

Create new album

Request Body

{
    "name": "我的相册",
    "description": "这是一个示例相册",
    "is_public": true
  }
GET /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
Copied to clipboard