Основные Функции

  • Поддержка загрузки изображений в нескольких форматах
  • Динамическая обработка и масштабирование изображений
  • Управление альбомами и категориями
  • Уведомления о событиях Webhook

Основная Информация

Базовый 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

API загрузки

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, макс. 10 МБ

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. POST-запросы будут отправлены на ваш настроенный URL при возникновении определенных событий.

Поддерживаемые События

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
Скопировано в буфер обмена