云手机

云手机是一台运行在云端的 Android 14 手机，你的代码通过 API 控制它。当某个应用没有 API 时就可以用它：手机上运行的是真实的应用，智能体或你自己的代码会像人一样操作它。

使用手机有两种方式：

• 手机智能体。 用平实的语言发送一个目标，例如“打开应用，搜索 Termux，告诉我第一个结果”。智能体会读取屏幕，点击、输入和滚动，直到完成目标，然后返回 answer。
• 直接控制。 由你自己的代码或智能体截图、读取屏幕上的元素，并发送点击、滑动、输入和按键操作。

任何人都可以在浏览器中实时观看屏幕，或接管操作。

手机与 Lovely Router 的其他服务共用同一个 API 密钥和预付费余额。手机在唤醒状态下每小时 $1.20，按分钟计费。智能体使用的模型另按其正常 API 价格计费。

运行你的第一个目标#

1. 1

   获取 API 密钥

   在 API 密钥 页面创建一个密钥并导出为环境变量。

   Shell

   export LOVELY_API_KEY="lr-..."

2. 2

   在新手机上启动运行

   POST /v1/phones/runs 会创建一台手机，安装你列出的应用，并让智能体开始处理你的目标。响应会立即返回，状态码为 202，并带有运行的 id。新手机启动大约需要一分钟，如果要先安装应用，时间会更长。

   cURLPythonNode.js

   Shell

   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. 3

   等待回答

   GET /v1/phones/runs/{id}?wait=50 会让请求最多挂起 50 秒，运行结束或向你提问时会提前返回。重复调用，直到 status 变为 succeeded、failed、stopped 或 waiting。加上 trace=1 可获取智能体的每一步。

   cURLPythonNode.js

   Shell

   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 把下一个目标发给同一台手机，或在 POST /v1/phones/runs 中传入 "phone_id"。之前运行中安装的应用和登录状态都还在。

手机的费用#

| | 价格 | | - | - | | 手机，唤醒时 | 每小时 $1.20，按分钟计费 | | 手机，休眠时 | 免费 | | 上传的 APK | 前 1 GB 免费，之后每 GB 每月 $0.30，按小时计费 | | 智能体运行 | 按模型正常的 API 价格按 token 计费（默认 gemini-3.8-flash，每步约 $0.003） |

手机闲置 5 分钟后会进入休眠，再次使用时约 2 秒即可唤醒，屏幕保持你离开时的样子。1 小时未使用的手机会被删除，其中的应用和数据也会一并删除。你也可以随时用 DELETE /v1/phones/{id} 自行删除。

启动一台手机需要余额中至少有 15 分钟的手机时长。余额用完后，运行会停止，手机进入休眠。每个账户最多同时拥有 3 台手机。

应用#

手机预装了 Chrome、设置等标准 Android 应用，以及 Google Play 服务。手机上没有 Play 商店，因此需要通过 APK 文件安装应用。任何 APK 都可以，拆分包（.apks、.xapk）也支持。.xapk 中的游戏数据（OBB 文件）也会复制到手机上。

• 手机启动时： 在创建手机或启动运行时，把应用列在 apps 中。每一项是指向文件的 https:// 链接，或你上传过的 APK 的名称。手机的 startup_apps 字段会显示每个应用的安装结果。
• 之后安装： 调用 POST /v1/phones/{id}/apps，请求体为 {"url": "https://…"} 或 {"apk": "myapp.apk"}。安装完成后请求才会返回。
• 你自己的 APK： 上传一次文件，之后即可在任何手机上按名称安装。100 MB 以内，用 PUT /v1/phones/apks/{name} 一次发送。500 MB 以内，用 POST /v1/phones/apks/{name}/uploads 分成 50 MB 的分片上传（做法）。更大的文件请自行托管，并通过 URL 安装。上传的前 1 GB 免费存储，超出部分每 GB 每月 $0.30。

# 上传一次
curl -X PUT https://lovelyrouter.com/v1/phones/apks/myapp.apk \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  --data-binary @myapp.apk

# 安装到手机上
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）只负责写最终答案和向你提问，所以快速运行的模型 token 费用也更低。快速模型本身已包含在手机价格中。

一个教练模型（费用已包含在手机价格中）在快速模型旁边工作：它为目标写一份简短的策略（比如游戏里优先走哪些步）和一条当前局面的提示，每隔几步或运行看起来卡住时重写。快速模型从不等它，每一步都使用最新的版本（用 "plan": false 可以关闭教练）。

如果某个操作后屏幕完全没变，在这个屏幕上就不会再试它，并立即告诉教练。在游戏中，除非游戏已结束或你的目标要求，智能体不会点「New Game」「Restart」或「Try again」。

快速模式适合游戏，以及简短明确的目标：关闭对话框、打开应用并搜索、按已知流程点击。需要判断的目标请用默认的 smart 模式，或者把大任务中简单快速的子任务交给快速智能体。

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 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 参考 中。