API 文檔

imgp.qzz.io 圖床提供 REST API，方便第三方應用、腳本或前端直接上傳圖片並獲取直鏈。

1. 基礎說明

Base URL： https://imgp.qzz.io/。以下路徑均相對於該域名。

所有 API 回應均為 JSON，且支援 CORS，可從瀏覽器或其它域名前端直接調用。

支援的圖片格式：JPG / JPEG / PNG。若圖片尺寸過小（長邊 < 1000px 或短邊 < 576px），服務端會自動按比例放大後再上傳。

2. 上傳圖片

請求

項目	說明
方法	POST
路徑	/api/upload.php
Content-Type	multipart/form-data
參數	表單欄位名 photo，值為圖片文件（必填）

POST /api/upload.php

成功回應（200）

{
  "success": true,
  "imageUrl": "https://imgp.qzz.io/i/example.jpg",
  "photoId": 23025
}

欄位	說明
success	是否成功，固定為 true
imageUrl	圖片直鏈，可直接用於外鏈或嵌入
photoId	後端圖床的圖片 ID（可選用於對賬）

錯誤回應（4xx / 5xx）

{
  "success": false,
  "error": "錯誤訊息說明"
}

常見錯誤：未帶 photo、文件無效、上游圖床異常等。

cURL 範例

curl -X POST "https://imgp.qzz.io/api/upload.php" \
  -F "photo=@/path/to/your/image.jpg"

JavaScript (fetch) 範例

const formData = new FormData();
formData.append('photo', fileInput.files[0]);

const res = await fetch('https://imgp.qzz.io/api/upload.php', {
  method: 'POST',
  body: formData
});
const data = await res.json();
if (data.success) {
  console.log('圖片直鏈:', data.imageUrl);
}

3. 獲取上傳列表（需鑑權）

用於查詢通過本平台已上傳的圖片記錄，需使用後台密碼進行 HTTP Basic 鑑權。

請求

項目	說明
方法	GET
路徑	/api/list.php
鑑權	Authorization: Basic base64(用戶名:密碼)，用戶名可任意（如 admin），密碼為後台設定之密碼

GET /api/list.php

成功回應（200）

{
  "uploads": [
    {
      "url": "https://imgp.qzz.io/i/example.jpg",
      "filename": "my-photo.jpg",
      "at": "2025-02-18 14:30:00",
      "photo_id": 23025
    }
  ]
}

未授權（401）

未帶 Authorization 或密碼錯誤時返回 401，並帶 WWW-Authenticate: Basic。

cURL 範例

curl -u "admin:YOUR_ADMIN_PASSWORD" "https://imgp.qzz.io/api/list.php"

4. 錯誤碼與 CORS

HTTP 狀態碼： 200 表示成功；400/405 表示請求有誤；401 表示需鑑權（僅 list）；500 表示服務端錯誤。

CORS： 支援跨域請求，預檢 OPTIONS 會返回 204。請求時可帶 Origin，服務端會回傳對應的 Access-Control-Allow-Origin。

如有對接問題，可聯繫 [email protected]。