tai-ch0802/pcloud

pCloud API 開發技能

概述

pCloud 是一個雲端儲存服務，提供 REST 風格的 HTTP JSON API 和二進位協議。主要功能：

• 檔案管理 — 上傳、下載、複製、重新命名、刪除、校驗碼
• 資料夾操作 — 建立、列表（遞迴）、重新命名、刪除、複製
• 分享 — 與其他使用者共享資料夾（檢視/編輯權限）
• 公開連結 — 為檔案和資料夾產生公開下載/串流連結
• 媒體串流 — 直接檔案連結、影片轉碼、音訊串流、HLS
• 壓縮封存 — 在伺服器端建立/解壓縮 ZIP 封存檔
• 縮圖 — 在伺服器端產生圖片/影片縮圖
• 收藏集 — 將檔案組織成虛擬收藏集
• 垃圾桶 — 列表、還原、清除已刪除項目
• 版本 — 列表和還原檔案版本
• 上傳連結 — 建立允許他人上傳到您帳號的連結
• 遠端上傳 — 從 URL 直接下載檔案到 pCloud

API 端點（資料中心）

[!IMPORTANT] pCloud 運營兩個資料中心。根據使用者的資料位置使用正確的主機名稱。

| 位置 | API 主機名稱 | OAuth 主機名稱 | |------|-------------|----------------| | 美國（locationid=1） | api.pcloud.com | my.pcloud.com | | 歐洲（locationid=2） | eapi.pcloud.com | e.pcloud.com |

OAuth 授權後，重新導向 URL 會包含 locationid 和 hostname 參數，指示該使用者應使用哪個 API 端點。務必儲存並使用每個使用者對應的正確主機名稱。

認證

OAuth 2.0（推薦）

起始頁面：https://my.pcloud.com/oauth2/authorize（美國）或 https://e.pcloud.com/oauth2/authorize（歐洲）

兩種流程：

1. 授權碼流程（伺服器應用） — 透過重新導向返回 code → 使用 oauth2_token 交換 access_token

   GET https://my.pcloud.com/oauth2/authorize?
     client_id=APP_ID&
     response_type=code&
     redirect_uri=REDIRECT_URI&
     state=RANDOM
   

   重新導向返回：?code=XXXXX&locationid=1&hostname=api.pcloud.com 然後使用 code + client_secret 呼叫 oauth2_token 取得 bearer token。

2. 隱式流程（純客戶端/行動應用） — 直接在重新導向片段中返回 access_token

   GET https://my.pcloud.com/oauth2/authorize?
     client_id=APP_ID&
     response_type=token&
     redirect_uri=REDIRECT_URI
   

   重新導向返回：#access_token=XXXXX&token_type=bearer&locationid=1&hostname=api.pcloud.com

使用認證令牌

在每個 API 呼叫中使用 Authorization 標頭傳遞 access_token：

GET https://api.pcloud.com/listfolder?folderid=0
Authorization: Bearer ACCESS_TOKEN

警告：請勿將 token 作為 URL 參數（?auth=...）或放在 multipart/form-data 欄位中傳遞。如果未使用標頭傳遞 token，pCloud API 可能會靜默拒絕請求或回傳 2000: Log in failed。

摘要登入（舊式）

1. 呼叫 getdigest 取得摘要
2. 呼叫 userinfo，帶 getauth=1&logout=1&username=EMAIL&digest=DIGEST&passworddigest=SHA1(PASSWORD+SHA1(USERNAME_LOWERCASE)+DIGEST)&authexpire=SECONDS
3. 回應包含 auth 令牌

HTTP JSON 協議

請求格式

所有方法接受 GET 和 POST。基底 URL：https://api.pcloud.com/METHOD_NAME

# GET 請求
curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/listfolder?folderid=0"

# POST 請求
curl -s -X POST "https://api.pcloud.com/listfolder" \
  -H "Authorization: Bearer TOKEN" \
  -d "folderid=0"

回應格式

// 成功
{ "result": 0, ... }

// 錯誤
{ "result": 2000, "error": "Log in required." }

檔案上傳

使用 POST 搭配 multipart/form-data。參數必須在檔案之前：

curl -s -X POST "https://api.pcloud.com/uploadfile" \
  -H "Authorization: Bearer TOKEN" \
  -F "folderid=0" \
  -F "file=@/path/to/file.jpg"

可在單一請求中上傳多個檔案。設定 renameifexists=1 以避免覆寫。

全域參數

這些可選參數適用於所有方法（在個別方法文件中省略）：

• authexpire — 令牌到期秒數（登入時）
• authinactiveexpire — 閒置 N 秒後到期
• device — 裝置識別字串

核心概念

識別碼

• 資料夾：folderid（整數）或 path（字串）。根目錄始終為 folderid=0
• 檔案：fileid（整數）或 path（字串）
• folderid/fileid 和 path 都可接受；若兩者都提供，folderid/fileid 優先

中繼資料結構

每個檔案/資料夾都會回傳中繼資料物件：

{
  "name": "file.jpg",
  "isfolder": false,
  "fileid": 1729212,
  "parentfolderid": 0,
  "size": 73269,
  "contenttype": "image/jpeg",
  "category": 1,
  "created": "Wed, 02 Oct 2013 14:29:11 +0000",
  "modified": "Wed, 02 Oct 2013 14:29:11 +0000",
  "hash": 10681749967730527559,
  "isshared": false,
  "ismine": true,
  "thumb": true,
  "icon": "image"
}

分類：0=未分類、1=圖片、2=影片、3=音訊、4=文件、5=封存檔

常用工作流程

列出資料夾內容

curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/listfolder?folderid=0&recursive=1"

上傳檔案

curl -s -H "Authorization: Bearer TOKEN" -F "folderid=0" -F "[email protected]" \
  https://api.pcloud.com/uploadfile

取得下載連結

curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/getfilelink?fileid=123"
# 回傳：{ "hosts": ["c123.pcloud.com"], "path": "/cfZka..." }
# 下載 URL：https://c123.pcloud.com/cfZka...

分享資料夾

curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/sharefolder?folderid=123&[email protected]&permissions=edit"

建立公開連結

curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/getfilepublink?fileid=123"

詳細參考

按需載入這些參考資料：

• 所有 API 方法（依分類）：參閱 api-methods.md 取得完整方法參考含參數和說明
• SDK 設定與使用：參閱 sdks.md 取得 JavaScript、PHP、Java、Swift、C SDK 詳情
• 錯誤碼：參閱 error-codes.md 取得錯誤碼表和疑難排解