Документация Clousd

Быстрый старт

Пять шагов от нового аккаунта до устройства, которым вы управляете из скрипта. Всё это можно сделать и вручную в панели.

1. Создайте аккаунт

   Зарегистрируйтесь через почту, Google или GitHub. Первое устройство работает 30 минут бесплатно, без карты и без пополнения.

2. Пополните баланс

   «Оплата → Пополнить», от $10 криптовалютой, через WeChat Pay или Alipay. Устройства списывают деньги с этого предоплаченного баланса; если он пуст, запрос на создание отвечает 402.

3. Создайте API-ключ

   «Настройки → API-ключи». Выберите права — read или control — и устройства, к которым у ключа будет доступ. Ключ показывается один раз.

4. Создайте устройство

   Получите список моделей, которые можно создать, и создайте устройство с сетью и тарифом.

5. Дождитесь запуска

   Устройство появляется в статусе starting и примерно через минуту переходит в running — уже со страной и адресом выхода.

export CLOUSD_KEY=cl_live_your_key

# 1. что можно создать? - id моделей и их версии Android
curl https://api.clousd.com/v1/models -H "Authorization: Bearer $CLOUSD_KEY"

# 2. создаём: Galaxy A16 5G на Android 15, мобильный выход в США, поминутно
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. опрашиваем, пока не запустится
curl https://api.clousd.com/v1/devices/c3f9a41d2 -H "Authorization: Bearer $CLOUSD_KEY"

Устройства

Устройство — это телефон одной модели на одной версии Android. Оно хранит приложения и данные при остановках и перезапусках, пока вы его не удалите.

Запуск, остановка и перезапуск отвечают 202 и задачей. Удаление необратимо: оно стирает устройство вместе с данными, отменить его нельзя. Тариф задаётся для каждого устройства: metered ($0.004 в минуту, не больше $0.80 в день) или monthly ($12.00 за 30 дней).

POST   /v1/devices/{name}/start
POST   /v1/devices/{name}/stop
POST   /v1/devices/{name}/restart
GET    /v1/devices/{name}/screenshot?w=320     # PNG, или небольшой JPEG с параметром w
POST   /v1/devices/{name}/action  {"op":"open_app","package":"com.android.chrome"}
DELETE /v1/devices/{name}                     # насовсем

action выполняет один шаг без живого потока: open_app, close_app, url, tap, swipe, text, key, scroll, а также шаги для работы с текстом find_text, tap_text, wait_text, screen_text.

Сеть

У каждого устройства один выход. GET /v1/network/options показывает типы и страны, доступные прямо сейчас.

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  # новый адрес, тот же тип и страна
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

Часовой пояс, язык, SIM и местоположение следуют за выходом. Выход работает ниже Android, DNS идёт через него, а если он пропадёт, трафик остановится. Как это устроено

Приложения

Ставьте приложения из нашего каталога так же, как телефон ставит их из Play Store, или загружайте любой APK.

GET  /v1/apps                                # пакет, название, категория, версия, размер
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # что установлено из каталога
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

Приложения из каталога указывают Play Store как источник установки. Если та же или более новая версия уже установлена, задача завершается со статусом «already».

Снапшоты и клоны

Снапшот замораживает устройство: приложения, входы в аккаунты, файлы и настройки. Восстановите его, чтобы вернуться назад, или клонируйте, чтобы создать новые устройства с той же настройкой, но со своими серийным номером, IMEI, SIM и Android ID.

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"}

Клоны — обычные устройства: оплачиваются как любые другие и попадают в список ключа, который их создал. Для резервных копий по расписанию используйте «Панель → Снапшоты → Ночная копия».

Группы и расписания

Групповая задача выполняет список шагов на многих устройствах, и каждое устройство начинает в случайный момент в пределах заданного разброса. Ход выполнения задача показывает по каждому устройству.

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"}
  ]
}

Шаги: open_app, close_app, install_app, url, tap, swipe, text, key, wait (случайная пауза от seconds до seconds_max), browse (случайные прокрутки и паузы, 10–600 с), scroll, if_text / unless_text (пропустить следующие шаги, если нужного текста нет на экране), screenshot, start, stop, restart.

Расписание — та же задача, только по часам: POST /v1/schedules с полями name, phones, steps, stagger, at ("HH:MM", UTC) и days (1–7). Поставить на паузу — /toggle, удалить — /delete. В панели раздел «Автоматизация» добавляет сценарии из плиток и готовые действия для популярных приложений. Что автоматизировано в каждом приложении

Доступ по ADB

ADB по умолчанию выключен. Включите его для устройства, указав адреса, с которых будете подключаться; вы получите хост, порт и одноразовый код входа — он показывается один раз.

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                 # выключить, закрыть сессии

Лимиты: allow_ips обязателен (до 20 IP или диапазонов); ttl_hours по умолчанию 24, максимум 168; до 3 сессий на устройство; 5 неверных кодов закрывают сессию, а 20 за 10 минут выключают реле; неактивные сессии закрываются через 30 минут; push и pull ограничены 2 GiB за сессию. Root, remount, disable-verity, reverse, reboot, tcpip, usb, jdwp, sideload и restore отклоняются всегда. Новый код закрывает активные сессии.

Вебхуки

У ключа может быть URL вебхука (задаётся при создании ключа). События по устройствам ключа приходят запросом POST с JSON-телом {"event", "ts", "phone", "job" | "incident"}.

В каждом запросе есть заголовок X-Clousd-Signature: HMAC-SHA256 от исходного тела в hex, где ключ — SHA-256 вашего API-ключа в hex. Доставка выполняется до трёх раз: сразу, через 10 секунд и через 60 секунд, с таймаутом 10 секунд.

ИИ-агенты

Два запроса дают агенту цикл: посмотреть, затем действовать.

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 всегда делает свежий скриншот и возвращает до 500 элементов экрана с их границами. act отказывает с 409 stale, если после переданного seq уже был другой observe или act, — так агент никогда не действует по старой картинке; с settle он ждёт, пока экран перестанет меняться (до 5 с). Между прогонами сбрасывайте устройство восстановлением снапшота. Телефоны для ИИ-агентов

Ошибки и лимиты

Ошибки приходят в JSON с машиночитаемым kind и сообщением: {"error": "busy", "message": "…"}. Коды статуса: 400 — неверный запрос, 401 — нет авторизации, 402 — недостаточно средств, 403 — запрещено правами ключа или списком устройств, 404 — не найдено, 409 — занято или устарело, 429 — превышен лимит запросов.

Лимиты на ключ: 60 запросов в минуту; на маршрутах /devices/{name}/… — 120 в минуту на устройство и 600 в минуту по всем устройствам. 429 означает: сбавьте темп и повторите с нарастающей паузой.

Команда и API-ключи

В аккаунте есть владельцы и операторы. Владельцы отвечают за оплату, API-ключи, команду, создание и удаление устройств. Операторы работают с назначенными им устройствами: запуск, остановка, приложения, сеть, снапшоты и ADB — но без оплаты, ключей и удаления. Приглашайте людей по почте в разделе «Команда»; они присоединяются при первом входе.

API-ключи принадлежат аккаунту, а не человеку: у каждого ключа есть права (read или control) и список устройств. Ключ на чтение, вызвавший изменяющий маршрут, получает 403. Отозванный ключ перестаёт работать сразу.

Оплата

Clousd работает на предоплаченном балансе. Пополнение от $10 криптовалютой, через WeChat Pay или Alipay; каждое пополнение и списание — строка в разделе «Оплата», а «Расход» показывает минуты и стоимость по каждому устройству. Поминутные устройства списывают $0.004 в минуту, пока работают, но не больше $0.80 в день; месячные списывают $12.00 раз в 30 дней. Android 15 добавляет 10%, Android 16 — 25%, Android 17 — 25%. Платные выходы в сеть оплачиваются за гигабайт. Когда баланс доходит до нуля, работающие поминутные устройства останавливаются, а их данные сохраняются. Цены

Помощь

Напишите на support@clousd.com или через форму обратной связи — ответит человек, обычно в течение рабочего дня. Укажите ID устройства из панели (он начинается с dev_) или его имя в API и то, что вы ожидали получить. Текущее состояние платформы — на странице статуса, а свежие изменения — в списке изменений.

Словарь

Слова, которыми пользуются панель, API и эта документация, — в одном месте.

Выход

Прокси, который назначен одному устройству и работает ниже Android: мобильный, резидентский, ISP, датацентр или ваш собственный SOCKS5- или HTTP-прокси. Приложения видят его адрес, а часовой пояс, язык и SIM следуют за его страной.

Регион

Где работает устройство. Выбирайте ближайший к тому, кто смотрит на экран или работает через ADB; регион выбирается отдельно от выхода.

Снапшот

Сохранённая копия всего устройства: приложения, входы в аккаунты, файлы и настройки. Восстанавливается в один шаг, из неё же можно клонировать новые устройства.

Клон

Новое устройство из снапшота: те же приложения, файлы и настройки, но свои серийный номер, IMEI, SIM, адреса Wi-Fi и Bluetooth и Android ID.

Личность

Аппаратные идентификаторы, которые сообщает устройство: серийный номер, IMEI, номер телефона и параметры Wi-Fi. Новая личность заменяет их одним запросом.

Рецепт

Готовая автоматизация одного действия в приложении — например, вход, прогрев, публикация поста или удаление последнего поста. Запускается на одном телефоне, на группе или по расписанию.

Общие шаги

Кирпичики, которые работают в любом приложении: открыть приложение или URL, нажать, провести, ввести текст, нажать клавишу, полистать, прокрутить, подождать, проверить текст на экране и сделать скриншот.

Сценарий

Цепочка шагов, собранная из плиток в разделе «Автоматизация», — например, вход, прогрев, пауза и публикация; у каждого шага своя длительность и разброс ±.

Группа

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

Расписание

Рецепты или шаги, которые запускаются по дням недели и времени (UTC) на устройстве или группе.

Ресурсы

Где хранятся аккаунты и медиа: данные для входа в каждый аккаунт, зашифрованные и привязанные к телефону, и медиатека.

Медиатека

Папки с фото и видео в «Ресурсах». Шаги публикации берут последний или случайный файл и никогда не повторяют файл на одном и том же телефоне.

Multi-view и синхронный ввод

Стена живых экранов рядом друг с другом. Синхронный ввод повторяет касание, свайп или набранный текст на выбранных телефонах.

Владелец и оператор

Роли в команде. Владельцы отвечают за оплату, API-ключи, команду, создание и удаление устройств; операторы работают только с назначенными им устройствами.

Реле ADB

Способ добраться до устройства через adb: подключитесь к реле и войдите по одноразовому коду. Только с ваших IP-адресов, по умолчанию выключено, работает ограниченное время.