| name | pcloud |
| description | 全面的 pCloud 雲端儲存 API 整合與 SDK 使用指南。適用於建構與 pCloud 互動的應用程式：(1) 檔案上傳/下載/管理、(2) 資料夾操作、(3) OAuth 2.0 認證、(4) 檔案/資料夾分享與公開連結、(5) 媒體串流（影片/音訊/HLS）、(6) 壓縮封存（zip/解壓縮）、(7) 縮圖、(8) 垃圾桶管理、(9) 檔案版本、(10) 收藏集、(11) 上傳連結，或 (12) 使用任何 pCloud SDK（JavaScript、PHP、Java、Swift、C）。 |
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（歐洲）
兩種流程：
-
授權碼流程（伺服器應用） — 透過重新導向返回 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。
-
隱式流程（純客戶端/行動應用） — 直接在重新導向片段中返回 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。
摘要登入（舊式）
- 呼叫
getdigest 取得摘要
- 呼叫
userinfo，帶 getauth=1&logout=1&username=EMAIL&digest=DIGEST&passworddigest=SHA1(PASSWORD+SHA1(USERNAME_LOWERCASE)+DIGEST)&authexpire=SECONDS
- 回應包含
auth 令牌
HTTP JSON 協議
請求格式
所有方法接受 GET 和 POST。基底 URL：https://api.pcloud.com/METHOD_NAME
curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/listfolder?folderid=0"
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":
分類：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 "file=@photo.jpg" \
https://api.pcloud.com/uploadfile
取得下載連結
curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/getfilelink?fileid=123"
分享資料夾
curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/sharefolder?folderid=123&mail=user@example.com&permissions=edit"
建立公開連結
curl -s -H "Authorization: Bearer TOKEN" "https://api.pcloud.com/getfilepublink?fileid=123"
詳細參考
按需載入這些參考資料：
