Lovely RouterДокументация
Получить ключ
Облачный телефон

Облачный телефон

Настоящие телефоны на Android 14 в облаке для ваших агентов. Устанавливайте любые APK, поручайте нашему телефонному агенту цель, сформулированную обычными словами, или управляйте телефоном сами — нажатиями, вводом текста и скриншотами.

Облачный телефон — это телефон на Android 14, который работает в облаке и которым ваш код управляет через API. Он пригодится, когда у приложения нет API: на телефоне запускается настоящее приложение, а агент или ваш собственный код работает с ним так же, как человек.

Телефон можно использовать двумя способами:

  • Телефонный агент. Отправьте цель обычными словами, например «Открой приложение, найди Termux и назови первый результат». Агент читает экран, нажимает, вводит текст и прокручивает, пока цель не будет достигнута, а затем возвращает answer.
  • Прямое управление. Ваш собственный код или агент делает скриншоты, читает элементы на экране и отправляет нажатия, свайпы, ввод текста и нажатия клавиш.

Человек может следить за экраном в реальном времени или перехватить управление из любого браузера.

Телефоны используют тот же API-ключ и предоплаченный баланс, что и остальные сервисы Lovely Router. Телефон стоит $1.20 в час, пока он активен, с поминутной тарификацией. Модели, которые использует агент, оплачиваются дополнительно по обычной цене API.

Запуск первой цели#

  1. Получите API-ключ

    Создайте ключ в разделе API-ключи и экспортируйте его.

    Shell
    export LOVELY_API_KEY="lr-..."

  2. Запустите цель на новом телефоне

    POST /v1/phones/runs создаёт телефон, устанавливает перечисленные приложения и запускает агента с вашей целью. Ответ приходит сразу — со статусом 202 и id запуска. Новый телефон запускается примерно за минуту, а если сначала нужно установить приложения, то дольше.

    curl https://lovelyrouter.com/v1/phones/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "goal": "Open the F-Droid app, search for Termux, and tell me the one-line summary of the first result.",
    "apps": ["https://f-droid.org/F-Droid.apk"]
  }'

  3. Дождитесь ответа

    GET /v1/phones/runs/{id}?wait=50 удерживает запрос до 50 секунд и отвечает раньше, если запуск завершился или агенту нужно что-то у вас спросить. Повторяйте запрос, пока status не станет succeeded, failed, stopped или waiting. Добавьте trace=1, чтобы получить шаги агента.

    curl "https://lovelyrouter.com/v1/phones/runs/prun_...?wait=50&trace=1" \
  -H "Authorization: Bearer $LOVELY_API_KEY"
    JSON
    {
  "id": "prun_7ae48d4cb099421dbd2c",
  "object": "phone.run",
  "phone_id": "ph_2758eedebf08496f87e0",
  "status": "succeeded",
  "steps": 6,
  "answer": "The first result is \"Termux Hub\": \"A lightweight Android app that indexes Termux tools from metadata.\"",
  "llm_usd": 0.0203
}

После запуска телефон остаётся за вами. Отправьте следующую цель на тот же телефон через POST /v1/phones/{phone_id}/runs или передайте "phone_id" в POST /v1/phones/runs. Приложения и выполненные входы в аккаунты из прошлых запусков сохраняются.

Сколько стоит телефон#

| | Цена | | - | - | | Телефон в активном состоянии | $1.20 в час, поминутная тарификация | | Телефон в спящем режиме | Бесплатно | | Загруженные APK | Первый 1 ГБ бесплатно, далее $0.30 за ГБ в месяц, почасовая тарификация | | Запуски агента | Обычная цена API модели за токен (по умолчанию gemini-3.8-flash, около $0,003 за шаг) |

Телефон засыпает после 5 минут бездействия и просыпается примерно за 2 секунды при следующем обращении — экран остаётся таким же, каким вы его оставили. Телефон, которым не пользовались 1 час, удаляется вместе с приложениями и данными. Вы можете удалить его сами в любой момент через DELETE /v1/phones/{id}.

Для запуска телефона на балансе должно хватать на 15 минут его работы. Когда баланс заканчивается, запуски останавливаются, а телефон засыпает. На одну учётную запись одновременно может приходиться не больше 3 телефонов.

Приложения#

На телефоне есть Chrome, «Настройки» и другие стандартные приложения Android, а также сервисы Google Play. Магазина Play Store нет, поэтому приложения устанавливаются из APK-файлов. Подходит любой APK, а также разделённые пакеты (.apks, .xapk). Игровые данные из .xapk (файлы OBB) тоже копируются на телефон.

  • При запуске телефона: перечислите приложения в apps, когда создаёте телефон или запускаете цель. Каждый элемент — ссылка https:// на файл или имя загруженного вами APK. Поле startup_apps телефона показывает, как прошла каждая установка.
  • Позже: POST /v1/phones/{id}/apps с {"url": "https://…"} или {"apk": "myapp.apk"}. Запрос возвращается, когда установка завершена.
  • Собственные APK: загрузите файл один раз и устанавливайте его по имени на любой телефон. Файл до 100 МБ отправляется одним запросом через PUT /v1/phones/apks/{name}. Файл до 500 МБ загружается частями по 50 МБ через POST /v1/phones/apks/{name}/uploads (как это сделать). Файл большего размера разместите у себя и устанавливайте по URL. Первый 1 ГБ загрузок хранится бесплатно; сверх этого хранение стоит $0.30 за ГБ в месяц.
# Upload once
curl -X PUT https://lovelyrouter.com/v1/phones/apks/myapp.apk \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  --data-binary @myapp.apk

# Install on a phone
curl https://lovelyrouter.com/v1/phones/ph_.../apps \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"apk": "myapp.apk"}'

Быстрый режим#

Когда скорость важнее тщательных рассуждений, запускайте цель с "mode": "fast". Быстрая модель принятия решений читает элементы экрана и выбирает большинство шагов значительно быстрее чем за секунду, тогда как чат-модели нужно несколько секунд. Вводимый текст она берёт из вашей цели и ваших ответов. Она также видит скриншот, поэтому может нажимать на то, что не является кнопками (игровые фишки, картинки), и делать свайпы. Она действует по лучшей догадке даже при неуверенности, потому что в игре любой ход лучше ожидания. Чат-модель (model) пишет только итоговый ответ и вопросы к вам, поэтому быстрый запуск ещё и тратит меньше токенов модели. Сама быстрая модель включена в цену телефона.

Параллельно с быстрой моделью работает модель-тренер (тоже включена в цену телефона): она пишет краткую стратегию для цели (например, какие ходы предпочитать в игре) и заметку о текущей ситуации и переписывает их каждые несколько шагов или когда запуск, похоже, застрял. Быстрая модель никогда её не ждёт: каждый шаг использует последнюю версию ("plan": false отключает тренера).

Ход, после которого экран не изменился, на этом экране больше не повторяется, и тренер сразу об этом узнаёт. В игре агент не нажимает New Game, Restart или Try again, если игра не окончена или этого не требует ваша цель.

Быстрый режим подходит для игр и коротких понятных целей: закрыть диалоги, открыть приложение и выполнить поиск, пройти по известному сценарию. Для целей, требующих рассудительности, используйте режим по умолчанию smart или поручайте быстрому агенту короткие подзадачи более крупной работы.

cURL
curl https://lovelyrouter.com/v1/phones/ph_.../runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"goal": "Open F-Droid and search for Termux", "mode": "fast"}'

Когда агенту нужны вы#

Если агенту нужно то, что знаете или должны решить только вы (код, пришедший на ваш номер телефона, пароль, выбор), статус запуска становится waiting, а в question сказано, что именно нужно. Ответьте через POST /v1/phones/runs/{id}/reply с {"answer": "…"}, и запуск продолжится. Можно также открыть экран в реальном времени, выполнить шаг самостоятельно и ответить done.

Агент никогда не платит, не отправляет деньги, не удаляет данные и ничего не публикует, если этого нет в цели. Остановить запуск можно в любой момент через POST /v1/phones/runs/{id}/stop.

Экран в реальном времени#

POST /v1/phones/{id}/screen возвращает ссылку на экран телефона в реальном времени. Она открывается в любом браузере, не требует плагинов и может быть встроена в iframe на вашей странице. Любой, у кого есть ссылка, может видеть экран и нажимать и вводить текст, поэтому делитесь ею только с тем, кто должен пользоваться телефоном. По умолчанию ссылка действует один час (ttl_seconds, до 24 часов). Экран повторяет ориентацию телефона: когда приложение переводит его в альбомный режим или вы отправляете rotate, он тоже поворачивается.

Самостоятельное управление телефоном#

Ваш собственный код или агент может управлять телефоном напрямую. Координаты задаются в пикселях скриншота, короткая сторона которого — 540 пикселей (540×1200 в портретной ориентации, 1200×540 в альбомной).

  • GET /v1/phones/{id}/screenshot возвращает экран в виде изображения WebP.
  • GET /v1/phones/{id}/elements перечисляет элементы на экране (кнопки, текст, поля), у каждого — центральная точка, размер и флаги, например clickable и editable.
  • POST /v1/phones/{id}/actions отправляет действие: tap, long_press, swipe, scroll, type (на любом языке), key (back, home, enter…), open_url, launch (по имени пакета), stop_app, wait, rotate (portrait или landscape) или shell (команда adb shell на телефоне). Добавьте "screenshot": true, чтобы получить экран после действия.
cURL
curl https://lovelyrouter.com/v1/phones/ph_.../actions \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"action": "tap", "x": 270, "y": 1116, "screenshot": true}'

Все поля и ошибки описаны в справочнике API.

← Назад
Вебхуки
Браузерный агент
Далее →
Облачные агенты
Облачный агент