黑色星期五充值赠礼
每笔符合条件的充值都可获赠额度,并可与其他优惠叠加。
11月30日截止
有些应用没有 API:唯一的入口就是屏幕。云手机是一台运行在云端的真实 Android 14 手机,你的代码通过 /v1/phones 操控它。从 APK 安装应用,然后用一句大白话把目标交给我们的手机智能体,或者在你自己的代码里点击、输入和滑动。人可以在任意浏览器里实时观看屏幕,或直接接管。手机在唤醒期间每小时 $1.20,按分钟计费,休眠时不收费。
交给你的 AI 智能体
把这段提示词复制到 Claude Code、Cursor、Codex 或任何编程智能体中。它会告诉智能体文档在哪里,以及如何使用你的 API 密钥。
Run an Android task for me on a Lovely Router cloud phone: create a phone, install the app I name, and let the phone agent do the goal, or drive it step by step. - Docs (read first): https://lovelyrouter.com/docs/phone.md and https://lovelyrouter.com/docs/api/phones.md - Phones: POST https://lovelyrouter.com/v1/phones creates one; install apps from an https URL or an uploaded APK; start an agent run with a plain-language goal and poll it; answer its questions at the run's reply endpoint. - Billed per awake minute while the phone is awake (asleep is free); delete the phone when you are done. - Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys. - Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large. - Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt. My task: <the app, the goal on the phone and what proves it worked>
操作手机的两种方式
| 手机智能体 | 直接控制 | |
|---|---|---|
| 你发送 | 一个目标:"打开这个应用,搜索 Termux,告诉我第一条结果" | 点击、滑动、输入和按键,一次一个动作 |
| 每一步由谁决定 | 我们的智能体读取屏幕并行动,直到目标完成 | 你的代码或你自己的智能体 |
| 你得到 | 一个 answer,加上 trace=1 时的步骤 | {"ok": true},以及(如果你要求)动作之后的屏幕 |
| 额外费用 | 聊天模型的 token,按其正常 API 价格计费 | 除手机外没有其他费用 |
两者用的是同一台手机,所以可以混着来:让智能体完成登录,然后自己截图并操控剩下的部分。
在新手机上执行目标
启动运行
POST /v1/phones/runs会创建一台手机、安装你列出的应用并启动智能体。它会立刻返回202、运行的id和phone_id。新手机大约需要一分钟启动,安装应用时更久。cURLcurl 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"] }'等待答案
GET /v1/phones/runs/{id}?wait=50最多挂起请求 50 秒,并在运行结束或向你提问时提前返回。Pythonimport os, requests API = "https://lovelyrouter.com/v1/phones" H = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"} run = requests.post(f"{API}/runs", headers=H, json={ "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"], }).json() while run["status"] in ("queued", "running"): run = requests.get(f"{API}/runs/{run['id']}", headers=H, params={"wait": 50}).json() print(run["status"], run["answer"])保留手机
运行结束后手机仍归你所有,应用和登录状态都在。用
POST /v1/phones/{phone_id}/runs向它发送下一个目标。Node.jsconst H = { Authorization: `Bearer ${process.env.LOVELY_API_KEY}`, 'content-type': 'application/json' }; const next = await (await fetch(`https://lovelyrouter.com/v1/phones/${phoneId}/runs`, { method: 'POST', headers: H, body: JSON.stringify({ goal: 'Open F-Droid and list the first three apps under Latest.', wait: 50 }), })).json(); console.log(next.status, next.answer);
手机智能体
智能体会读取屏幕内容,点击、输入和滚动,直到目标完成。写目标时把任务需要的每个值都写进去,最多 10,000 个字符。每次运行最多 200 步(max_steps,默认 40),并可用模型列表中的任意聊天模型作为 model;默认是 gemini-3.8-flash。
(默认):由聊天模型决定每一步,每步几秒钟。用于需要判断的目标。
("mode": "fast"):由快速决策模型根据屏幕元素和截图在远不到一秒内选出大部分步骤,因此它也能点击不是按钮的东西,比如棋子和图片,并可以滑动。一个教练模型在旁边写一份简短策略,每隔几步或运行看起来卡住时重写。两者都包含在手机价格里;聊天模型只负责写最终答案,所以快速运行用的 token 也更少。快速模式适合游戏、关闭弹窗和按已知流程点击。
如果智能体需要短信验证码、密码或某个决定,运行会变成 waiting 并带上 question。用 POST /v1/phones/runs/{id}/reply 回答,或者在实时屏幕上自己完成这一步并回复 done。
除非目标里写明,智能体从不付款、转账、删除数据或公开发布内容。POST /v1/phones/runs/{id}/stop 会在当前步骤结束后终止运行。
任意应用,来自 APK
手机上装有 Chrome、设置和标准 Android 应用,以及 Google Play 服务,但没有 Play Store。应用来自 APK 文件:任意 .apk,以及 .apks 或 .xapk 形式的分包,其游戏数据(OBB 文件)也会一并复制到手机上。
- 通过 URL:创建手机时在
apps中最多列出 20 个https://链接,或之后用POST /v1/phones/{id}/apps安装一个。 - 通过上传:用
PUT /v1/phones/apks/{name}一次性存好自己的 APK(单次请求最大 100 MB),然后在任意手机上按名称安装。最大 500 MB 的文件按 50 MB 分片上传,分片可以乱序或同时发送。
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_2758eedebf08496f87e0/apps \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"apk": "myapp.apk"}'自己操控屏幕
你自己的代码,或你自己构建的智能体,可以直接操作手机。坐标是截图的像素,截图短边为 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、open_url、launch、stop_app、wait、rotate或shell。加上"screenshot": true可查看结果。
curl https://lovelyrouter.com/v1/phones/ph_2758eedebf08496f87e0/actions \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"action": "type", "text": "weather Tokyo", "submit": true, "screenshot": true}'实时屏幕,竖屏或横屏
POST /v1/phones/{id}/screen 返回手机实时屏幕的链接。它在任意浏览器中无需插件即可打开,也可以嵌在你自己的页面的 iframe 里,让你的用户可以看着智能体工作,或手动完成登录。任何拿到链接的人都能点击和输入,所以只分享给该用这台手机的人;链接默认有效一小时,最长 24 小时。当应用转为横屏,或你发送 rotate 时,截图变为 1200×540,实时屏幕也随之旋转。在浏览器里,手机控制台 无需写代码就能完成这一切。
常见问题
什么是云手机?+
一台运行在云端而不是你手里的 Android 14 手机。它运行真实的 Android 应用,你的代码通过 API 访问它:截图、屏幕元素、动作、应用安装和实时屏幕链接。
能从 Play Store 安装应用吗?+
不能。手机有 Google Play 服务但没有 Play Store,所以你要从 APK 文件安装应用:通过 https:// 链接,或上传一次文件再按名称安装。分包(.apks、.xapk)也可以。
我能同时运行多少台手机?+
每个账户同时可以有 3 台手机。一台手机一次只执行一个目标;在第一个结束前,对同一台手机发起的第二次运行会得到 409。
手机空闲时收费吗?+
最多 5 分钟。5 分钟无操作后手机休眠,在你再次使用前不产生费用。1 小时未使用后会被删除。
我自己的智能体能控制手机吗?+
可以。把截图、元素接口和动作接口作为工具给它,或者让它把想交出去的部分交给我们的手机智能体来运行。
别人能观看或帮助智能体吗?+
可以。实时屏幕链接能在任意浏览器中显示手机,并允许对方点击和输入。当智能体需要验证码或某个选择时,它会等待你的回复。