クラウドスマホ

クラウドスマホ

エージェントのための、クラウド上の本物の Android 14 スマホ。任意の APK をインストールし、普段の言葉でゴールを伝えてスマホエージェントに任せることも、タップ、入力、スクリーンショットで自分で操作することもできます。

クラウドスマホは、クラウド上で動く Android 14 スマホで、コードから API で操作できます。API のないアプリを扱いたいときに使います。スマホでは本物のアプリが動き、エージェントやあなたのコードが人と同じようにそれを操作します。

スマホの使い方は 2 通りあります。

スマホエージェント。 「アプリを開いて Termux を検索し、最初の結果を教えて」のように、ゴールを普段の言葉で送ります。エージェントは画面を読み取り、タップ、入力、スクロールを繰り返してゴールを達成し、answer を返します。
直接操作。 あなたのコードやエージェントがスクリーンショットを撮り、画面上の要素を読み取り、タップ、スワイプ、入力、キー操作を送ります。

画面はどのブラウザからでもリアルタイムで見られ、人が操作を引き継ぐこともできます。

API キーとプリペイド残高は Lovely Router の他のサービスと共通です。スマホは起動中 1 時間あたり $1.20 で、分単位で課金されます。エージェントが使うモデルの料金は、通常の API 料金で別途かかります。

最初のゴールを実行する#

1
API キーを取得する
API キーでキーを作成し、環境変数に設定します。
Shell
```
export LOVELY_API_KEY="lr-..."
```
2
新しいスマホで実行を開始する
POST /v1/phones/runs はスマホを作成し、指定したアプリをインストールして、エージェントにゴールの作業を始めさせます。レスポンスはステータス 202 と実行の id を含んですぐに返ります。新しいスマホの起動には 1 分ほどかかり、先にアプリをインストールする場合はさらに時間がかかります。
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"]
  }'
```

回答を待つ

GET /v1/phones/runs/{id}?wait=50 はリクエストを最大 50 秒待機させ、実行が終わるか、あなたへの質問が発生した時点で早めに返ります。status が succeeded、failed、stopped、waiting のいずれかになるまで繰り返してください。trace=1 を付けるとエージェントのステップも取得できます。

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" を渡します。以前の実行で入れたアプリやログイン状態はそのまま残っています。

スマホの料金#

スマホは 5 分間使われないとスリープし、再び使うと約 2 秒で復帰します。画面は離れたときのままです。1 時間使われなかったスマホは、アプリやデータごと削除されます。DELETE /v1/phones/{id} でいつでも自分で削除することもできます。

スマホを起動するには、残高にスマホ 15 分分の金額が必要です。残高がなくなると、実行は止まり、スマホはスリープします。1 つのアカウントで同時に持てるスマホは 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} で 1 回のリクエストで送ります。500 MB までは POST /v1/phones/apks/{name}/uploads で 50 MB ずつのパートに分けてアップロードします（方法）。それより大きいファイルは自分でホストし、URL でインストールしてください。アップロードの最初の 1 GB は無料で保存され、それを超える分は 1 GB あたり月 $0.30 です。

Shell

# 一度アップロードする
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" で実行を始めます。高速な判断モデルが画面の要素を読み、ほとんどのステップを 1 秒未満で選びます。チャットモデルなら 1 ステップに数秒かかります。入力するテキストは、ゴールとあなたの回答から選ばれます。スクリーンショットも見るので、ボタンではないもの（ゲームの駒や画像）をタップしたり、スワイプしたりもできます。自信がなくても最も良さそうな手を打ちます。ゲームではどんな手でも待つよりましだからです。チャットモデル（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 で埋め込むこともできます。リンクを持っている人は画面を見るだけでなく、タップや入力もできるため、そのスマホを使うべき人にだけ共有してください。リンクの有効期間はデフォルトで 1 時間です（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 は操作を 1 つ送ります。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 リファレンスにあります。