核心特性

  • 多格式图片上传支持
  • 动态图片处理和缩放
  • 相册和分类管理
  • Webhook 事件通知

基础信息

Base URL: https://api.pichub.app/v1
协议: HTTPS Only
格式: JSON
编码: UTF-8

身份认证

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

上传接口

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

在线测试

支持 JPG, PNG, GIF, WebP 格式,最大 10MB

1 100
响应结果

                                                

                                                

图片管理

GET /images

获取用户的图片列表,支持分页和相册筛选

查询参数

参数 类型 默认值 说明
page integer 1 页码
per_page integer 20 每页数量
album_id string - 按相册筛选

在线测试

响应结果

                                                    

                                                    
DELETE /images/{id}

删除指定的图片

警告

此操作不可逆,删除后无法恢复

相册管理

POST /albums

创建新相册

请求体

{
    "name": "我的相册",
    "description": "这是一个示例相册",
    "is_public": true
  }
GET /albums

获取用户的相册列表

Webhooks

PicHub 支持 Webhook 事件通知,当特定事件发生时会向您配置的 URL 发送 POST 请求。

支持的事件

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
已复制到剪贴板