圖片轉連結標誌

API 文件

API 僅對有效的 Pro / Premium 訂閱開放。使用金鑰驗證後,上傳的圖片會進入與工作台相同的資源庫,額度與網頁付費方案一致。

產品圖託管

上傳圖片

向 /api/v1/upload 發起 POST(multipart/form-data)。

參數

Authorization
必填。請求頭,格式 Bearer 你的 API 金鑰。
file
必填。二進位檔案,或 base64 資料。
name
可選。檔名;以 multipart 上傳本機檔案時會自動偵測。

範例呼叫

二進位檔案

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=@./product.jpg"

Base64

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \
  -F "name=pixel.gif"

上傳本機檔案請一律使用 POST。本介面不支援以 GET 上傳。

回傳欄位

id
資源庫中的圖片 id。
url
可直接用在商品頁的 CDN 連結。
fileName
原始檔名。
fileSize
檔案大小(位元組)。
mimeType
上傳檔案的 MIME 類型。
createdAt
上傳時間(UTC),格式 YYYY-MM-DD HH:mm:ss。
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
  "fileName": "product.jpg",
  "fileSize": 128472,
  "mimeType": "image/jpeg",
  "createdAt": "2026-11-05 10:20:30"
}

列出圖片

GET /api/v1/images,可用 page、pageSize(最大 100)。

curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

回傳欄位

resources
圖片陣列:id、fileName、url、fileSize、mimeType、createdAt。
page
目前頁碼。
pageSize
每頁筆數。
total
資源庫圖片總數。
{
  "resources": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fileName": "product.jpg",
      "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
      "fileSize": 128472,
      "mimeType": "image/jpeg",
      "createdAt": "2026-11-05 10:20:30"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

刪除圖片

DELETE /api/v1/images/:id。會同時刪除儲存檔案與資源庫記錄。

curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

回傳欄位

success
刪除成功時為 true。
{ "success": true }

額度說明

免費帳號不可用 API。Pro / Premium 依方案的上傳次數、儲存與單檔上限執行。超限時 API 回傳錯誤,並可能包含 upgradeUrl。

錯誤說明

失敗時回傳 error 欄位;額度類錯誤可能帶 upgradeUrl。

  • dailyLimitReached— 達到每日上傳上限(HTTP 429)。
  • storageLimitReached— 儲存空間不足(HTTP 413)。
  • fileTooLarge— 檔案超過方案單檔上限(HTTP 400)。
  • 401— 缺少、無效或已撤銷的 API 金鑰。
{
  "error": "dailyLimitReached",
  "errorParams": { "limit": 1000 },
  "plan": "paid",
  "limit": 1000,
  "upgradeUrl": "https://www.phototourl.com/pricing"
}