API 文档 - PicHub

核心特性

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

基础信息

Base URL: https://pichub.app/v1

协议: HTTPS Only

格式: JSON

编码: UTF-8

身份认证

PicHub API 使用 Bearer 令牌进行身份认证。您需要在每个请求的 Authorization 头中包含有效的 API 密钥。

获取您的 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://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

参数

参数	类型	必需	说明
image	file	是	图片文件 (JPG, PNG, WebP, GIF)
album_id	string	否	相册 ID
description	string	否	图片描述

交互式测试

API Token *

图片文件 *

支持 JPG, PNG, WebP, GIF 格式

图片质量

1 100

图片描述

转换为 WebP 格式

响应结果

图片管理

GET /images

获取图片列表，支持分页和筛选

查询参数

参数	类型	默认值	说明
page	integer	1	页码
per_page	integer	20	每页数量（最大100）
album_id	string	-	筛选特定相册

DELETE /images/{id}

删除指定图片

警告

此操作不可逆转。图片及其所有变换将被永久删除。

相册管理

POST /albums

创建新相册

请求体

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

GET /albums

获取相册列表

Webhooks

设置 Webhooks 来接收图片上传、删除等事件的实时通知。

支持的事件

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(file, albumId, description) {
  const formData = new FormData();
  formData.append('image', file);
  formData.append('album_id', albumId);
  formData.append('description', description);
  try {
    const response = await fetch('https://pichub.app/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://pichub.app/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

导航

开发者API文档