English
Русский
简体中文
繁體中文
Tiếng Việt
Bahasa Indonesia
Português
Español云手机API：REST接口、Webhook和ADB中继
Clousd API是面向安卓云手机的REST API，地址为https://api.clousd.com/v1，管的是手机，不是电话线路。控制台里的每个操作，你都可以自己调用：创建设备、更换网络、安装应用、快照和克隆。耗时任务返回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全部接口及所有字段见参考文档。第一次用？从五步快速入门开始。
设备
生命周期屏幕与输入
控制网络
出口应用
像从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": "…"}
| 状态码 | 含义 | 错误类型 |
|---|---|---|
| 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接口
可以通过互联网使用ADB吗？
可以，通过我们的中继：为设备开启ADB，把你的IP地址加入白名单，用adb connect连接，再用一次性验证码登录。ADB默认关闭，24小时后自动关闭，你也可以设为最长7天。
完整的参考文档在哪里？
在/docs/reference/，根据OpenAPI描述自动生成，也可以下载openapi-v1.yaml。
在哪里查看API是否正常？
在API状态页面：对API以及支撑实时画面和ADB的网关做真实检测，最多每五分钟一次，保留90天的每日记录。