Cloud phone API: REST và ADB

Q: Tôi tạo thiết bị qua API được không?

Được. GET /v1/models liệt kê những gì bạn tạo được; POST /v1/devices kèm mẫu máy, kết nối mạng và gói sẽ tạo một thiết bị. Gửi header Idempotency-Key để lần thử lại sau khi hết thời gian chờ không bao giờ tạo hay tính phí hai lần.

Q: AI agent dùng API thế nào?

GET /v1/devices/{name}/observe trả về ảnh chụp màn hình mới cùng các phần tử trên màn hình và vị trí của chúng; POST /v1/devices/{name}/act chạm, gõ hoặc vuốt rồi chờ đến khi màn hình ổn định. API observe và act cho AI agent

Clousd API là REST API tại https://api.clousd.com/v1 dành cho điện thoại Android đám mây, không phải đường dây điện thoại. Mọi thao tác trên bảng điều khiển đều là lệnh gọi bạn tự thực hiện được: tạo thiết bị, đổi kết nối mạng, cài ứng dụng, tạo snapshot và nhân bản. Tác vụ dài trả về 202, khóa API có phân quyền, webhook có chữ ký, và ADB chỉ cách bạn một câu lệnh.

Lấy khóa API Tham chiếu API

RESTJSON qua HTTPS 202+ job cho tác vụ dài webhook

GET /v1/devices

curl https://api.clousd.com/v1/devices \
  -H "Authorization: Bearer cl_live_••••••••"

200 OKPhản hồi

{ "devices": [
  { "name": "c3f9a41d2", "model": "Galaxy A16 5G",
    "android": "15", "state": "running",
    "exit": { "type": "mobile", "country": "DE",
              "timezone": "Europe/Berlin" },
    "uptime": 7740, "minutes_today": 129 }
] }

Khóa API rõ ràng, dễ kiểm soát.

Tạo khóa trong Cài đặt → Khóa API. Mỗi khóa có phạm vi quyền và danh sách thiết bị được phép tác động, và chỉ hiện một lần. Thu hồi ngay tại đó bất cứ khi nào cần.

đọc hoặc điều khiểnKhóa đọc chỉ xem được, không thay đổi gì; khóa điều khiển thì thao tác được.
Giới hạn theo thiết bịKhóa chỉ thấy các thiết bị trong danh sách của nó, cùng những thiết bị mới do nó tạo hoặc nhân bản.
Giới hạn tần suất theo khóa60 yêu cầu mỗi phút, và tối đa 120 yêu cầu mỗi phút cho mỗi thiết bị trên các route thiết bị.

Base URL và xác thực

# mọi request
https://api.clousd.com/v1
Authorization: Bearer cl_live_your_key

# thao tác lâu trả về 202 kèm một job
POST /v1/devices/c3f9a41d2/restart
→ 202 { "job": { "id": "3f9c…", "kind": "restart", "state": "running" } }
GET  /v1/jobs/3f9c…
→ 200 { "job": { "state": "done" } }

Những lệnh gọi bạn sẽ dùng.

Đây là những lệnh hầu hết script bắt đầu; mọi route API v1 với đầy đủ các trường có trong tài liệu tham chiếu. Mới bắt đầu? Hãy xem hướng dẫn nhanh năm bước.

Thiết bị

vòng đời

GET/v1/modelsNhững gì bạn tạo được

POST/v1/devicesTạo thiết bị

GET/v1/devicesDanh sách thiết bị

POST/v1/devices/{name}/startBật · tắt · khởi động lại

DELETE/v1/devices/{name}Xóa vĩnh viễn

Màn hình và thao tác

điều khiển

GET/v1/devices/{name}/screenshotPNG, hoặc JPEG nhẹ

POST/v1/devices/{name}/actionMở app, chạm, gõ, tìm chữ

POST/v1/devices/{name}/inputChạm và phím thô

GET/v1/devices/{name}/logsLogcat gần đây

Mạng

kết nối

GET/v1/network/optionsLoại và quốc gia đang bán

POST/v1/devices/{name}/networkĐổi kết nối

POST/v1/devices/{name}/network/rotateĐịa chỉ mới

POST/v1/network/checkKiểm tra proxy của bạn

Ứng dụng

như từ Play

GET/v1/appsKho ứng dụng

POST/v1/devices/{name}/appsCài từ danh mục

GET/v1/devices/{name}/appsNhững gì đã cài

POST/v1/devices/{name}/apkTải APK của bạn lên

Snapshot

trạng thái

POST/v1/devices/{name}/snapshotsLưu trạng thái

POST/v1/devices/{name}/snapshots/{id}/restoreQuay về

POST/v1/devices/{name}/snapshots/{id}/cloneThiết bị mới từ snapshot

Dàn máy

nhiều thiết bị

POST/v1/groupsChạy các bước trên nhiều thiết bị

GET/v1/schedulesLịch chạy hằng tuần

GET/v1/healthTình trạng thiết bị

GET/v1/usageSố phút mỗi thiết bị

Theo công việc: snapshot và bản sao, đổi kết nối mạng của máy, chạy test từ CI.

ADB, không cần mở cổng.

Không thiết bị nào mở ADB ra Internet. Bạn kết nối tới relay của chúng tôi, đăng nhập bằng mã dùng một lần, và relay chuyển phiên của bạn tới đúng thiết bị đó, không đi đâu khác. Relay tắt cho đến khi bạn bật.

Chỉ IP của bạnMuốn bật phải có danh sách cho phép, tối đa 20 địa chỉ hoặc dải địa chỉ.
Có thời hạnMặc định 24 giờ, tối đa 7 ngày, sau đó tự tắt.
Mọi thứ đều chạyinstall, shell, logcat, push và pull. Lệnh nguy hiểm như root hay reboot bị từ chối.

Terminal

# 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

Cơ chế bảo vệ	Điều gì xảy ra	Giới hạn
Địa chỉ được phép	Kết nối từ bất kỳ nơi nào khác bị đóng ngay	tối đa 20 IP hoặc dải
Hết hạn	Relay của thiết bị tự tắt và mã bị xóa	mặc định 24 giờ, tối đa 7 ngày
Phiên	Kết nối thứ tư bị từ chối	3 phiên cùng lúc mỗi thiết bị
Nhập sai mã	Phiên bị đóng; sau 20 lần sai, relay của thiết bị tự tắt	5 lần mỗi phiên · 20 lần mỗi 10 phút
Phiên không hoạt động	Bị đóng; shell và logcat đang chạy không tính là không hoạt động	30 phút
Push và pull	Các lần truyền tệp tiếp theo trong phiên đó bị từ chối	2 GiB mỗi phiên
Luôn bị từ chối	Cả disable-verity, reverse, tcpip, usb, jdwp, sideload, restore	root, remount, reboot, …

Webhook có chữ ký.

Gán cho khóa một URL webhook, nền tảng sẽ gửi tới đó mỗi khi có chuyện xảy ra trên các thiết bị của khóa: một job hoàn tất, một thiết bị gặp sự cố, sự cố được khắc phục.

EVENTjob.finishedstart, stop, network, snapshot, clone…

EVENThealth.problemthiết bị cần được xử lý

EVENThealth.resolvedđã ổn trở lại

Ba lần gửi: ngay lập tức, sau 10 giây và sau một phút. Mỗi yêu cầu kèm X-Clousd-Signature.

Xác minh chữ ký · Python

import hashlib, hmac

# khóa bí mật HMAC là chuỗi hex SHA-256 của khóa API của bạn
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": {…}}

Lỗi rõ ràng, dễ xử lý.

Mã trạng thái HTTP chuẩn, kèm phần thân JSON gồm kind cho máy đọc và thông điệp cho người đọc: {"error": "busy", "message": "…"}

Trạng thái	Ý nghĩa	Kind
400	Thiếu một trường hoặc giá trị không nằm trong danh sách cho phép	bad_request
401	Khóa bị thiếu, sai hoặc đã thu hồi	unauthorized
402	Không đủ số dư cho yêu cầu này	insufficient_funds
403	Phạm vi quyền hoặc danh sách thiết bị của khóa không cho phép	forbidden
404	Khóa này không có thiết bị, job hoặc snapshot đó	not_found
409	Thiết bị đã ở trạng thái đó hoặc đang bận job khác	busy
429	Quá nhiều yêu cầu: giãn ra rồi thử lại	rate_limited

Câu hỏi về cloud phone API

Cần hỏi gì khác? Hãy nhắn cho bộ phận hỗ trợ, người thật sẽ trả lời, thường trong một ngày làm việc.

API có tốn thêm phí không?

Không. API, webhook và ADB đều có sẵn. Bạn trả tiền cho thiết bị khi chúng chạy: $0.004 mỗi phút hoặc $12.00 mỗi tháng. Không chia gói, tài khoản nào cũng có API

Tôi tạo thiết bị qua API được không?

Được. GET /v1/models liệt kê những gì bạn tạo được; POST /v1/devices kèm mẫu máy, kết nối mạng và gói sẽ tạo một thiết bị. Gửi header Idempotency-Key để lần thử lại sau khi hết thời gian chờ không bao giờ tạo hay tính phí hai lần.

Có SDK không?

API là REST thuần, dùng được từ mọi ngôn ngữ có HTTP client. SDK Python và MCP server cho AI agent sẽ ra mắt cùng chương trình truy cập sớm cho agent.

AI agent dùng API thế nào?

GET /v1/devices/{name}/observe trả về ảnh chụp màn hình mới cùng các phần tử trên màn hình và vị trí của chúng; POST /v1/devices/{name}/act chạm, gõ hoặc vuốt rồi chờ đến khi màn hình ổn định. API observe và act cho AI agent

Tôi dùng ADB qua Internet được không?

Được, qua relay của chúng tôi: bật ADB cho thiết bị, cho phép các địa chỉ IP của bạn, kết nối bằng adb connect và đăng nhập bằng mã dùng một lần. ADB mặc định tắt và tự tắt sau 24 giờ, hoặc tối đa 7 ngày nếu bạn chọn.

Tài liệu tham chiếu đầy đủ ở đâu?

Tại /docs/reference/, dựng từ mô tả OpenAPI, bạn cũng có thể tải về dưới dạng openapi-v1.yaml.

Xem API có đang hoạt động ở đâu?

Trên trang trạng thái API: kiểm tra thực tế API và gateway phía sau màn hình trực tiếp và ADB, chạy tối đa năm phút một lần, kèm lịch sử theo ngày trong 90 ngày.

Dùng thử miễn phí

Lấy khóa. Viết script cho thiết bị đầu tiên trong một phút.

Không cần thẻ, không cần nạp tiền.
Tạo tài khoản, khởi chạy một thiết bị và dùng thử trong nửa giờ.
Nếu hợp việc, bạn nạp tiền và dùng tiếp. Nếu không, bạn cũng chẳng mất gì.

Tạo tài khoản Đọc tài liệu

Máy đã tắt không tính phíMỗi tài khoản một lần dùng thử, thiết bị giữ nguyên trạng thái