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"
}