データツール

データツールは Web から構造化データを返します。Google マップの場所、TikTok のコメント、LinkedIn のプロフィール、Amazon のレビュー、求人情報、任意の Web ページの Markdown などです。ツールを見つけて JSON の入力を送ると、JSON で結果が返ります。各実行はプリペイド残高から課金されます。料金は呼び出し料金と結果単価の合計で、設定した上限を超えることはありません。

別のアカウントやサブスクリプションは不要です。モデルに使う API キーがそのままツールにも使え、ツールの利用額は同じ残高とキーの利用上限に計上されます。

試してみる#

カタログは公開されています。キーなしで一覧を取得できます。

curl https://lovelyrouter.com/v1/tools

ツールの実行にはキーが必要です。次の実行は Austin のコーヒーショップを最大 20 件探し、費用は最大 $0.00551 です。

curl https://lovelyrouter.com/v1/tools/google-maps-places/run \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "input": {"searchTerms": ["coffee shop"], "location": "Austin, Texas, USA"},
    "max_results": 20
  }'

レスポンスには、実行のステータス、かかった費用、items に入った結果が含まれます。長時間の実行、ポーリング、ページネーションについてはツールを実行するを参照してください。

カタログの内容#

各ツールはいずれか 1 つのカテゴリに属します。GET /v1/tools?category=reviews のようにカテゴリ ID で絞り込むか、ツールページで閲覧できます。

ツールは随時追加されます。最新の一覧は GET /v1/tools とツールページで常に確認できます。

料金の仕組み#

各ツールには 2 種類の料金があり、どちらも 0 の場合があります。

• 呼び出し料金：成功した実行に対して 1 回だけ課金されます。
• 結果単価：実行が返した結果 1 件ごとに課金されます。単位はツールによって異なり、場所、レビュー、ページ、プロフィールなどです。

1 回の実行の費用は次のとおりです。

per-call fee + per-result fee × results returned

現在の価格での例：

価格は変更されることがあります。各ツールの最新価格は、ツールページと GET /v1/tools の price オブジェクトで確認できます。

max_results で費用に上限を設ける#

すべての実行には結果数の上限 max_results があります。実行がこの上限を超えて結果を返したり課金したりすることはありません。省略するとツールの default_results が適用され、ツール自体の max_results まで引き上げられます。

そのため、実行の最大費用は開始前に分かります：per-call fee + per-result fee × max_results（呼び出し料金 + 結果単価 × max_results）。

仮押さえと精算#

1. 仮押さえ。 実行の開始時に、最大費用が残高から仮押さえされます。残高またはキーの利用上限で賄えない場合、実行は 402 で拒否され、何も課金されません。max_results を下げるか、チャージしてください。
2. 精算。 実行が終わると、実際に返った分だけが課金され、仮押さえの残りは残高に戻ります。

上限 20 件の Google マップ検索では $0.00551 が仮押さえされます。14 件の場所が返った場合、支払いは $0.004082 で、$0.001428 が残高に戻ります。

失敗した実行と停止した実行#

結果を 1 件も返さずに失敗した実行は無料です。すべての実行とその課金額は、ダッシュボードのツールに表示されます。

実行の流れ#

1. 1

   ツールを見つける

   カタログを一覧・検索するか、プランナーにタスクを説明します。最適なツールを見つけるを参照してください。

2. 2

   入力スキーマを読む

   GET /v1/tools/{id} は、ツールの input_schema、example_input、価格を返します。

3. 3

   実行を開始する

   input と上限 max_results を付けて POST /v1/tools/{id}/run を呼び出します。最大費用が残高から仮押さえされます。

4. 4

   待つかポーリングする

   リクエストはデフォルトで最大 60 秒待ちます。時間内に終わった実行は 200 と結果を返します。それより長い実行は 202 を返すので、終了するまで GET /v1/tools/runs/{run_id} をポーリングします。

5. 5

   精算して結果を読む

   終了した実行は results、charge_usd、items 内のデータを返します。誰もポーリングしない実行も数分以内に自動で精算されるため、仮押さえが残り続けることはありません。

ブラウザエージェント#

ブラウザエージェントも同じカタログに browser-agent という ID で含まれています。目標と開始 URL を渡すと、実際のブラウザでタスクを進めます。課金は結果単位ではなくステップ単位で、max_results は最大ステップ数になります。ログイン、構造化出力、人による承認を含む API の全体はブラウザエージェントを参照してください。

制限#

同時実行数の上限を超えた実行は 429 で拒否されます。他の実行が終わってから、もう一度開始してください。

次のステップ#