English
Русский
简体中文
繁體中文
Tiếng Việt
Bahasa Indonesia
Português
EspañolAndroid 雲手機 API：REST 與 ADB
Clousd API 是位於 https://api.clousd.com/v1 的 REST API，對象是 Android 雲手機，不是電話門號。控制台裡的每個操作，你都能自己用呼叫完成：建立裝置、更換網路、安裝 App、拍快照和複製。耗時的工作回傳 202，金鑰有權限範圍，Webhook 附簽章，ADB 只要一行指令。
curl https://api.clousd.com/v1/devices \ -H "Authorization: Bearer cl_live_••••••••"
{ "devices": [
{ "name": "c3f9a41d2", "model": "Galaxy A16 5G",
"android": "15", "state": "running",
"exit": { "type": "mobile", "country": "DE",
"timezone": "Europe/Berlin" },
"uptime": 7740, "minutes_today": 129 }
] }
權限一目了然的金鑰。
在「設定 → API 金鑰」建立金鑰。每把金鑰都有權限範圍和可操作的裝置清單，而且只顯示一次。需要時隨時可以在那裡撤銷。
- 唯讀或控制唯讀金鑰只能看、不能改；控制金鑰可以執行操作。
- 限定裝置金鑰只看得到清單上的裝置，以及它自己建立或複製出來的新裝置。
- 每把金鑰的速率限制每分鐘 60 個請求；裝置相關路由每台裝置每分鐘最多 120 個。
# 每個請求都要帶 https://api.clousd.com/v1 Authorization: Bearer cl_live_your_key # 耗時操作回傳 202 與一個工作 POST /v1/devices/c3f9a41d2/restart → 202 { "job": { "id": "3f9c…", "kind": "restart", "state": "running" } } GET /v1/jobs/3f9c… → 200 { "job": { "state": "done" } }
你會用到的呼叫。
大多數腳本都從這些開始；所有 API v1 路由和每個欄位都在參考文件裡。第一次用？從五步驟快速入門開始。
裝置
生命週期畫面與輸入
控制網路
出口App
如同從 Play 安裝快照
狀態機隊
多台裝置ADB，不用開放連接埠。
沒有任何裝置會把 ADB 暴露在網路上。你連到我們的中繼，用一次性代碼登入，中繼只會把你的連線轉送到那台裝置，其他一概不通。你開啟之前，它都是關閉的。
- 只限你的 IP必須設定白名單才能開啟，最多 20 個位址或網段。
- 有時效預設 24 小時，最長 7 天，時間到會自動關閉。
- 功能一應俱全install、shell、logcat、push 和 pull 都能用。root、reboot 這類危險指令一律拒絕。
# the dashboard or POST /v1/devices/{name}/adb gives host, port and code adb connect relay.clousd.com:27001 adb -s relay.clousd.com:27001 shell clousd-login a1b2c3 login ok adb -s relay.clousd.com:27001 install app-release.apk adb -s relay.clousd.com:27001 logcat -d | tail -40
| 防護 | 會發生什麼 | 限制 |
|---|---|---|
| 允許的位址 | 來自其他任何地方的連線會立刻關閉 | 最多 20 個 IP 或網段 |
| 到期 | 該裝置的中繼關閉，代碼清除 | 預設 24 小時，最長 7 天 |
| 連線數 | 第四個連線會被拒絕 | 每台裝置同時 3 個 |
| 代碼錯誤 | 連線關閉；累計 20 次後，該裝置的中繼會關閉 | 每個連線 5 次 · 每 10 分鐘 20 次 |
| 閒置連線 | 自動關閉；正在跑的 shell 和 logcat 不算閒置 | 30 分鐘 |
| Push 與 pull | 該連線後續的檔案傳輸會被拒絕 | 每個連線 2 GiB |
| 一律拒絕 | 另外還有 disable-verity、reverse、tcpip、usb、jdwp、sideload、restore | root, remount, reboot, … |
Webhook，附簽章。
替金鑰設定 Webhook URL，只要這把金鑰的裝置有動靜，平台就會發送通知：工作完成、裝置出現問題、問題排除。
最多傳送三次：立即一次、10 秒後一次、一分鐘後一次。每個請求都帶有 X-Clousd-Signature。
import hashlib, hmac # HMAC 密鑰是你 API 金鑰的 SHA-256 十六進位雜湊值 secret = hashlib.sha256(API_KEY.encode()).hexdigest().encode() expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, headers["X-Clousd-Signature"]): raise PermissionError("bad signature") # body: {"event": "job.finished", "ts": …, "phone": "c3f9a41d2", "job": {…}}
好處理的錯誤。
標準 HTTP 狀態碼，加上 JSON 內容，包含程式可判讀的 kind 和給人看的訊息：{"error": "busy", "message": "…"}
| 狀態碼 | 代表什麼 | kind |
|---|---|---|
| 400 | 欄位缺漏，或不是允許的值 | bad_request |
| 401 | 金鑰缺漏、錯誤或已撤銷 | unauthorized |
| 402 | 餘額不足以執行你要求的操作 | insufficient_funds |
| 403 | 金鑰的權限範圍或裝置清單不允許 | forbidden |
| 404 | 這把金鑰找不到該裝置、工作或快照 | not_found |
| 409 | 裝置已經是那個狀態，或正忙於其他工作 | busy |
| 429 | 請求太多：先等一下再重試 | rate_limited |
雲手機 API 常見問題
還有其他問題？寫信給客服，由真人回覆，通常一個工作天內。
API 要另外收費嗎？
不用。API、Webhook 和 ADB 都包含在內。你只需支付裝置運作期間的費用：每分鐘 $0.004，或每月 $12.00。沒有分級方案，每個帳號都能用 API
可以透過 API 建立裝置嗎？
可以。GET /v1/models 會列出可以建立的機型；帶上機型、網路和方案呼叫 POST /v1/devices 就能建立一台。記得加上 Idempotency-Key 標頭，逾時後重試也絕不會重複建立或重複扣款。
有 SDK 嗎？
API 是純 REST，任何有 HTTP 用戶端的語言都能用。Python SDK 和給 AI Agent 用的 MCP 伺服器，會隨 Agent 搶先體驗一起推出。
AI Agent 怎麼使用？
GET /v1/devices/{name}/observe 會回傳最新截圖，以及畫面上的元素和它們的位置；POST /v1/devices/{name}/act 負責點擊、輸入或滑動，並等畫面穩定。給 AI Agent 用的 observe 與 act API
可以透過網路使用 ADB 嗎？
可以，透過我們的中繼：替裝置開啟 ADB、允許你的 IP 位址，用 adb connect 連線，再以一次性代碼登入。ADB 預設關閉，24 小時後會自動關閉；你也可以設定最長 7 天。
完整參考文件在哪裡？
在 /docs/reference/，由 OpenAPI 描述自動產生，也可以下載 openapi-v1.yaml。
哪裡可以看 API 是否正常？
請看 API 狀態頁面：實際檢查 API，以及即時畫面和 ADB 背後的閘道，最多每五分鐘一次，保留 90 天的每日紀錄。