Автоматизация Android-эмулятора: REST API и ADB

Q: Можно ли создавать устройства через API?

Да. GET /v1/models показывает, что можно создать; POST /v1/devices с моделью, сетью и тарифом создаёт устройство. Передавайте заголовок Idempotency-Key, чтобы повтор после таймаута никогда не создал устройство и не списал деньги дважды.

Q: Как им пользуются ИИ-агенты?

GET /v1/devices/{name}/observe возвращает свежий скриншот и элементы экрана с их координатами; POST /v1/devices/{name}/act нажимает, вводит текст или делает свайп и ждёт, пока экран успокоится. API observe и act для ИИ-агентов

Clousd API — это REST API по адресу https://api.clousd.com/v1 для облачных Android-телефонов, а не телефонных линий. Любое действие из панели можно выполнить запросом самому: создать устройство, сменить ему сеть, установить приложения, сделать снапшот и клон. Долгие операции отвечают 202, у ключей есть права, вебхуки подписаны, а до ADB — одна команда.

Получить API-ключ Справочник API

RESTJSON по HTTPS 202+ задача для долгих операций вебхуки

GET /v1/devices

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

200 OKОтвет

{ "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 в минуту на устройство для маршрутов устройств.

Базовый URL и авторизация

# каждый запрос
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 со всеми полями — в справочнике. Впервые здесь? Начните с быстрого старта в пять шагов.

Устройства

жизненный цикл

GET/v1/modelsЧто можно создать

POST/v1/devicesСоздайте устройство

GET/v1/devicesСписок телефонов

POST/v1/devices/{name}/startЗапуск · остановка · перезапуск

DELETE/v1/devices/{name}Удалить насовсем

Экран и ввод

управление

GET/v1/devices/{name}/screenshotPNG или лёгкий JPEG

POST/v1/devices/{name}/actionОткрыть приложение, нажать, ввести, найти текст

POST/v1/devices/{name}/inputКасания и клавиши напрямую

GET/v1/devices/{name}/logsСвежий logcat

Сеть

выходы

GET/v1/network/optionsТипы и страны в продаже

POST/v1/devices/{name}/networkСменить выход

POST/v1/devices/{name}/network/rotateНовый адрес

POST/v1/network/checkПроверить свой прокси

Приложения

как из Play

GET/v1/appsКаталог

POST/v1/devices/{name}/appsУстановить из каталога

GET/v1/devices/{name}/appsЧто установлено

POST/v1/devices/{name}/apkЗагрузить свой APK

Снапшоты

состояние

POST/v1/devices/{name}/snapshotsСохранить состояние

POST/v1/devices/{name}/snapshots/{id}/restoreОткатить

POST/v1/devices/{name}/snapshots/{id}/cloneНовое устройство из снапшота

Парк

много устройств

POST/v1/groupsШаги на многих устройствах

GET/v1/schedulesНедельные расписания

GET/v1/healthСостояние ваших устройств

GET/v1/usageМинуты по устройствам

По задачам: снапшоты и клоны, смена сети телефона, тесты из CI.

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 за сессию · 20 за 10 мин
Простой сессии	Сессия закрывается; живой shell и logcat простоем не считаются	30 минут
Push и pull	Дальнейшая передача файлов в этой сессии отклоняется	2 GiB за сессию
Запрещено всегда	А также disable-verity, reverse, tcpip, usb, jdwp, sideload, restore	root, remount, reboot, …

Подписанные вебхуки.

Укажите для ключа URL вебхука, и платформа будет отправлять на него запрос, когда что-то происходит с устройствами этого ключа: завершилась задача, у устройства появилась проблема, проблема устранена.

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

EVENThealth.problemустройству нужно внимание

EVENThealth.resolvedвсё снова в порядке

Три попытки доставки: сразу, через 10 секунд и через минуту. В каждом запросе есть X-Clousd-Signature.

Проверка подписи · Python

import hashlib, hmac

# секрет HMAC - SHA-256 hex-дайджест вашего API-ключа
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, вебхуки и ADB входят в цену. Вы платите за устройства, пока они работают: $0.004 в минуту или $12.00 в месяц. Без тарифных уровней, API в каждом аккаунте

Можно ли создавать устройства через API?

Да. GET /v1/models показывает, что можно создать; POST /v1/devices с моделью, сетью и тарифом создаёт устройство. Передавайте заголовок Idempotency-Key, чтобы повтор после таймаута никогда не создал устройство и не списал деньги дважды.

Есть ли SDK?

API — это обычный REST, он работает с любого языка, где есть HTTP-клиент. Python SDK и MCP-сервер для ИИ-агентов появятся вместе с ранним доступом для агентов.

Как им пользуются ИИ-агенты?

GET /v1/devices/{name}/observe возвращает свежий скриншот и элементы экрана с их координатами; POST /v1/devices/{name}/act нажимает, вводит текст или делает свайп и ждёт, пока экран успокоится. API observe и act для ИИ-агентов

Можно ли пользоваться ADB через интернет?

Да, через наше реле: включите ADB для устройства, разрешите свои IP-адреса, подключитесь командой adb connect и войдите по одноразовому коду. По умолчанию ADB выключен и сам выключается через 24 часа — или через срок до 7 дней, если вы так выберете.

Где полный справочник?

По адресу /docs/reference/. Он собран из описания OpenAPI, которое можно скачать файлом openapi-v1.yaml.

Где посмотреть, работает ли API?

На странице статуса API: настоящие проверки API и шлюза, через который работают живые экраны и ADB, не чаще раза в пять минут, с историей по дням за 90 дней.

Пробный период

Получите ключ. Первое устройство из скрипта — за минуту.

Без карты и пополнения.
Создайте аккаунт, запустите телефон и работайте с ним полчаса.
Подошло — пополните баланс и продолжайте. Не подошло — вы ничего не теряете.

Создайте аккаунт Читать документацию

Остановленный телефон бесплатенОдин пробный период на аккаунт, телефон сохраняет всё