Remote ADB qua Internet và bắt đầu với API

Bắt đầu nhanh

Năm bước từ tài khoản mới đến một thiết bị bạn điều khiển bằng script. Mọi việc ở đây cũng làm được bằng tay trên bảng điều khiển.

1. Tạo tài khoản

   Đăng ký bằng email, Google hoặc GitHub. Thiết bị đầu tiên chạy miễn phí 30 phút, không cần thẻ, không cần nạp tiền.

2. Nạp số dư

   Thanh toán → Nạp tiền, từ $10 bằng crypto, WeChat Pay hoặc Alipay. Thiết bị trừ tiền vào số dư trả trước này; hết số dư thì lệnh tạo trả về 402.

3. Tạo khóa API

   Cài đặt → Khóa API. Chọn phạm vi quyền, read hoặc control, và các thiết bị khóa được dùng. Khóa chỉ hiện một lần.

4. Tạo thiết bị

   Liệt kê các mẫu máy bạn tạo được, rồi tạo một máy kèm kết nối mạng và gói.

5. Theo dõi máy khởi động

   Thiết bị hiện trạng thái starting và chuyển sang running sau khoảng một phút, kèm quốc gia và địa chỉ của kết nối.

export CLOUSD_KEY=cl_live_your_key

# 1. tạo được những gì? - mã mẫu máy kèm phiên bản Android
curl https://api.clousd.com/v1/models -H "Authorization: Bearer $CLOUSD_KEY"

# 2. tạo máy: Galaxy A16 5G chạy Android 15, kết nối di động tại Hoa Kỳ, tính phí theo phút
curl -X POST https://api.clousd.com/v1/devices \
  -H "Authorization: Bearer $CLOUSD_KEY" \
  -H "Idempotency-Key: first-device-001" \
  -d '{"profile":"galaxya16","plan":"metered","network":{"type":"mobile","country":"US"}}'
# → 202 {"ok": true, "name": "c3f9a41d2", "state": "starting", "poll": "/v1/devices/c3f9a41d2"}

# 3. hỏi lại cho tới khi máy chạy
curl https://api.clousd.com/v1/devices/c3f9a41d2 -H "Authorization: Bearer $CLOUSD_KEY"

Thiết bị

Thiết bị là một chiếc điện thoại thuộc một mẫu máy, chạy một phiên bản Android. Thiết bị giữ ứng dụng và dữ liệu qua các lần tắt và khởi động lại cho đến khi bạn xóa.

Bật, tắt và khởi động lại trả về 202 kèm một job. Xóa là vĩnh viễn: xóa thiết bị cùng dữ liệu và không thể hoàn tác. Gói tính theo từng thiết bị: metered ($0.004 mỗi phút, tối đa $0.80 một ngày) hoặc monthly ($12.00 cho 30 ngày).

POST   /v1/devices/{name}/start
POST   /v1/devices/{name}/stop
POST   /v1/devices/{name}/restart
GET    /v1/devices/{name}/screenshot?w=320     # PNG, hoặc JPEG nhỏ khi có w
POST   /v1/devices/{name}/action  {"op":"open_app","package":"com.android.chrome"}
DELETE /v1/devices/{name}                     # xóa vĩnh viễn

action chạy một bước mà không cần luồng hình trực tiếp: open_app, close_app, url, tap, swipe, text, key, scroll, cùng các hàm hỗ trợ chữ find_text, tap_text, wait_text, screen_text.

Mạng

Mỗi thiết bị có một kết nối mạng. GET /v1/network/options liệt kê các loại và quốc gia bạn chọn được ngay lúc này.

POST /v1/devices/{name}/network         {"type":"residential","country":"GB"}
POST /v1/devices/{name}/network         {"url":"socks5://user:pass@203.0.113.7:1080"}
POST /v1/devices/{name}/network/rotate  # địa chỉ mới, cùng loại và quốc gia
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

Múi giờ, ngôn ngữ, SIM và vị trí báo cáo đi theo kết nối. Kết nối được áp dụng bên dưới Android, DNS đi qua nó, và lưu lượng dừng lại nếu kết nối rớt. Cách hoạt động

Ứng dụng

Cài từ kho ứng dụng của chúng tôi giống như điện thoại cài từ Play Store, hoặc tải lên APK bất kỳ.

GET  /v1/apps                                # gói, tên, danh mục, phiên bản, dung lượng
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # những gì đã cài từ kho ứng dụng
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

Ứng dụng cài từ kho báo Play Store là nguồn cài đặt. Nếu máy đã có cùng phiên bản hoặc bản mới hơn, job kết thúc với “already”.

Snapshot và bản sao

Snapshot đóng băng thiết bị: ứng dụng, phiên đăng nhập, tệp và cài đặt. Khôi phục để quay lại; nhân bản để tạo thiết bị mới cùng cấu hình, mỗi máy có số serial, IMEI, SIM và Android ID riêng.

POST /v1/devices/{name}/snapshots                  {"name":"ready-v3"}
GET  /v1/devices/{name}/snapshots
POST /v1/devices/{name}/snapshots/{id}/restore
POST /v1/devices/{name}/snapshots/{id}/clone    {"name":"eu01"}

Bản sao là thiết bị bình thường, tính phí như mọi thiết bị khác, và được thêm vào danh sách của khóa đã tạo ra chúng. Muốn sao lưu theo lịch, dùng Bảng điều khiển → Snapshot → Sao lưu hằng đêm.

Nhóm và lịch chạy

Job nhóm chạy một danh sách bước trên nhiều thiết bị, mỗi thiết bị bắt đầu vào một thời điểm ngẫu nhiên trong khoảng trễ bạn đặt. Tiến độ được báo theo từng thiết bị trong job.

POST /v1/groups
{
  "phones":  ["c3f9a41d2", "c81d07e5a", "c2b9f4a10"],
  "stagger": [30, 180],
  "steps": [
    {"op":"install_app","package":"com.instagram.android"},
    {"op":"open_app","package":"com.instagram.android"},
    {"op":"browse","seconds":240},
    {"op":"wait","seconds":20,"seconds_max":90},
    {"op":"screenshot"}
  ]
}

Các bước: open_app, close_app, install_app, url, tap, swipe, text, key, wait (ngẫu nhiên giữa seconds và seconds_max), browse (cuộn và dừng ngẫu nhiên, 10–600 giây), scroll, if_text / unless_text (bỏ qua các bước tiếp theo nếu trên màn hình không có một đoạn chữ nhất định), screenshot, start, stop, restart.

Lịch chạy là cùng job đó nhưng chạy theo đồng hồ: POST /v1/schedules với name, phones, steps, stagger, at ("HH:MM", UTC) và days (1–7). Tạm dừng bằng /toggle, xóa bằng /delete. Trên bảng điều khiển, mục Tự động hóa có thêm luồng tác vụ ghép từ các khối và thao tác dựng sẵn cho ứng dụng phổ biến. Mỗi ứng dụng tự động hóa được những gì

Truy cập ADB

ADB mặc định tắt. Bật cho một thiết bị kèm các địa chỉ bạn sẽ kết nối từ đó; bạn nhận host, cổng và mã đăng nhập dùng một lần, chỉ hiện một lần.

POST /v1/devices/{name}/adb  {"ttl_hours":24,"allow_ips":["203.0.113.7","198.51.100.0/24"]}
# → {"host": "…", "port": 27001, "code": "a1b2c3", "expires": "…",
#    "connect": "adb connect host:27001", "login": "adb -s host:27001 shell clousd-login a1b2c3"}

adb connect host:27001
adb -s host:27001 shell clousd-login a1b2c3      # → login ok
adb -s host:27001 install app.apk

DELETE /v1/devices/{name}/adb                 # tắt, đóng các phiên

Giới hạn: bắt buộc có allow_ips (tối đa 20 IP hoặc dải); ttl_hours mặc định 24 và tối đa 168; tối đa 3 phiên mỗi thiết bị; 5 lần sai mã sẽ đóng phiên và 20 lần trong 10 phút sẽ tắt relay; phiên không hoạt động tự đóng sau 30 phút; push và pull giới hạn 2 GiB mỗi phiên. Root, remount, disable-verity, reverse, reboot, tcpip, usb, jdwp, sideload và restore luôn bị từ chối. Cấp mã mới sẽ đóng các phiên đang mở.

Webhook

Khóa API có thể có URL webhook (đặt khi tạo khóa). Sự kiện của các thiết bị thuộc khóa được gửi tới dưới dạng POST với thân JSON {"event", "ts", "phone", "job" | "incident"}.

Mỗi yêu cầu kèm X-Clousd-Signature: HMAC-SHA256 dạng hex của phần thân gốc, với khóa là SHA-256 dạng hex của khóa API của bạn. Hệ thống gửi tối đa ba lần: ngay lập tức, sau 10 giây và sau 60 giây, mỗi lần chờ tối đa 10 giây.

AI agent

Hai lệnh gọi tạo cho agent một vòng lặp: nhìn, rồi thao tác.

GET /v1/devices/{name}/observe?w=540
# → {"seq": 41, "image": {"w": 540, "format": "jpeg", "data": "…"}, "package": "…", "activity": "…",
#    "ui": [{"text": "Checkout", "id": "…", "b": [60, 1560, 1020, 1680], "click": true}, …]}

POST /v1/devices/{name}/act  {"op":"tap_text","text":"Checkout","seq":41,"settle":true}
# → {"ok": true, "seq": 42, "settled": true, "waited_ms": 830}

observe luôn chụp ảnh màn hình mới và trả về tối đa 500 phần tử trên màn hình kèm tọa độ. act từ chối với 409 stale nếu đã có lệnh observe hoặc act khác sau seq bạn truyền vào, nên agent không bao giờ thao tác trên hình cũ; với settle, lệnh chờ đến khi màn hình ngừng thay đổi (tối đa 5 giây). Khôi phục snapshot để làm mới giữa các lần chạy. Điện thoại cho AI agent

Lỗi và giới hạn

Lỗi trả về dạng JSON với kind cho máy đọc và thông điệp: {"error": "busy", "message": "…"}. Mã trạng thái: 400 yêu cầu sai, 401 chưa xác thực, 402 không đủ số dư, 403 bị chặn bởi phạm vi quyền hoặc danh sách thiết bị, 404 không tìm thấy, 409 đang bận hoặc đã cũ, 429 vượt giới hạn tần suất.

Giới hạn theo khóa: 60 yêu cầu mỗi phút; trên các route /devices/{name}/… là 120 yêu cầu mỗi phút cho mỗi thiết bị và 600 yêu cầu mỗi phút trên tất cả thiết bị. Gặp 429 nghĩa là hãy chậm lại và thử lại với thời gian chờ tăng dần.

Đội ngũ và khóa API

Một tài khoản có chủ tài khoản và nhân viên vận hành. Chủ tài khoản lo thanh toán, khóa API, đội ngũ, và việc tạo hoặc xóa thiết bị. Nhân viên vận hành chạy những thiết bị bạn giao: bật, tắt, ứng dụng, mạng, snapshot và ADB, nhưng không có quyền thanh toán, khóa API hay xóa. Mời mọi người qua email trong mục Đội ngũ; họ tham gia ngay lần đăng nhập đầu tiên.

Khóa API thuộc về tài khoản, không thuộc về cá nhân: mỗi khóa có phạm vi quyền (read hoặc control) và danh sách thiết bị. Khóa đọc gọi một route làm thay đổi dữ liệu sẽ nhận 403. Thu hồi là khóa ngừng hoạt động ngay.

Thanh toán

Clousd dùng số dư trả trước. Nạp từ $10 bằng crypto, WeChat Pay hoặc Alipay; mỗi lần nạp và mỗi khoản trừ là một dòng trong mục Thanh toán, còn mục Sử dụng hiện số phút và chi phí theo từng thiết bị. Thiết bị theo phút trừ $0.004 mỗi phút khi chạy, không bao giờ quá $0.80 một ngày; thiết bị gói tháng trừ $12.00 một lần cho mỗi 30 ngày. Android 15 cộng thêm 10%, Android 16 thêm 25% và Android 17 thêm 25%. Kết nối mạng trả phí tính theo gigabyte. Khi số dư về 0, các thiết bị theo phút đang chạy sẽ tắt và vẫn giữ dữ liệu. Bảng giá

Nhận hỗ trợ

Viết thư tới support@clousd.com hoặc dùng biểu mẫu liên hệ; người thật sẽ trả lời, thường trong một ngày làm việc. Hãy kèm ID thiết bị trên bảng điều khiển (bắt đầu bằng dev_) hoặc tên API của nó, và điều bạn mong đợi xảy ra. Tình trạng hiện tại của nền tảng có trên trang trạng thái, còn những thay đổi gần đây nằm trong ghi chú phát hành.

Thuật ngữ

Những thuật ngữ mà bảng điều khiển, API và tài liệu này dùng, gom về một chỗ.

Kết nối

Proxy gắn cho một thiết bị, bên dưới Android: di động, dân cư, ISP, datacenter hoặc proxy SOCKS5 hay HTTP của chính bạn. Ứng dụng thấy địa chỉ của nó, còn múi giờ, ngôn ngữ và SIM đi theo quốc gia của nó.

Khu vực

Nơi thiết bị chạy. Chọn khu vực gần nhất với người xem màn hình hoặc chạy ADB; khu vực được chọn tách biệt với kết nối mạng.

Snapshot

Bản lưu toàn bộ thiết bị: ứng dụng, phiên đăng nhập, tệp và cài đặt. Khôi phục chỉ trong một bước, hoặc nhân bản thiết bị mới từ đó.

Nhân bản

Thiết bị mới tạo từ một snapshot: cùng ứng dụng, tệp và cài đặt, nhưng có số serial, IMEI, SIM, địa chỉ Wi-Fi và Bluetooth cùng Android ID riêng.

Thông tin máy

Các mã định danh phần cứng mà thiết bị báo ra: serial, IMEI, số điện thoại và thông số Wi-Fi. Thông tin mới thay toàn bộ các mã đó chỉ bằng một lệnh gọi.

Kịch bản

Tác vụ tự động dựng sẵn cho một thao tác trong ứng dụng, như Đăng nhập, Nuôi nick, Đăng bài hay Xóa bài gần nhất, chạy trên một máy, một nhóm hoặc theo lịch.

Bước chung

Các khối dùng được trong mọi ứng dụng: mở ứng dụng hoặc URL, chạm, vuốt, gõ chữ, bấm phím, lướt, cuộn, chờ, kiểm tra chữ trên màn hình và chụp ảnh màn hình.

Luồng tác vụ

Chuỗi bước ghép từ các khối trong mục Tự động hóa, như Đăng nhập, Nuôi nick, Tạm dừng và Đăng bài, mỗi bước có thời lượng và biên độ ±.

Nhóm

Tập thiết bị bạn thao tác cùng lúc: bật, tắt, cài ứng dụng và chạy các bước, với độ trễ ngẫu nhiên giữa các máy.

Lịch chạy

Kịch bản hoặc các bước chạy theo ngày trong tuần và giờ (UTC) trên một thiết bị hoặc một nhóm.

Tài nguyên

Nơi lưu tài khoản và media: thông tin đăng nhập của từng tài khoản, được mã hóa và gắn với một máy, cùng thư viện Media.

Thư viện Media

Các thư mục ảnh và video trong Resources. Bước đăng bài lấy tệp mới nhất hoặc ngẫu nhiên và không bao giờ đăng lại một tệp trên cùng một máy.

Multi-view và Sync

Lưới màn hình trực tiếp đặt cạnh nhau. Sync sao chép một lần chạm, vuốt hay đoạn chữ đã gõ tới các máy bạn chọn.

Chủ tài khoản và nhân viên vận hành

Vai trò trong đội. Chủ tài khoản lo thanh toán, khóa API, đội ngũ và việc tạo hoặc xóa thiết bị; nhân viên vận hành chỉ chạy những thiết bị được giao.

Relay ADB

Cách bạn truy cập thiết bị bằng adb: kết nối tới relay và đăng nhập bằng mã dùng một lần. Chỉ IP của bạn, mặc định tắt, có thời hạn.