Инструменты данных

Инструменты данных возвращают структурированные данные из интернета: результаты веб-поиска, любую веб-страницу в виде Markdown, места из Google Maps, комментарии в TikTok, профили LinkedIn, отзывы с Amazon, вакансии. Вы находите инструмент, отправляете ему входные данные в JSON и получаете результаты тоже в JSON. Каждый запуск оплачивается с предоплаченного баланса: плата за вызов плюс плата за каждый результат, и никогда не больше заданного вами лимита.

Отдельная учётная запись или подписка не нужны. API-ключ, который вы используете для моделей, работает и для инструментов, а расходы на инструменты списываются с того же баланса и учитываются в лимитах расходов ключа.

Попробуйте#

Каталог открыт для всех. Получить его список можно без ключа:

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

Для запуска инструмента нужен ключ. Этот запуск находит до 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. О долгих запусках, опросе статуса и постраничном чтении рассказано в разделе Запуск инструмента.

Что есть в каталоге#

Каждый инструмент относится к одной категории. Фильтруйте по её идентификатору через GET /v1/tools?category=reviews или просматривайте категории на странице инструментов.

Со временем добавляются новые инструменты. GET /v1/tools и страница инструментов всегда показывают актуальный список.

Как устроена оплата#

У каждого инструмента две цены, любая из которых может быть нулевой:

• Плата за вызов списывается один раз за успешный запуск.
• Плата за результат списывается за каждый результат, который вернул запуск. Единица зависит от инструмента: место, отзыв, страница, профиль.

Стоимость запуска:

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.

Сначала резерв, потом расчёт#

1. Резерв. При старте запуска его максимальная стоимость резервируется на вашем балансе. Если баланса или лимита расходов ключа не хватает, запуск отклоняется с кодом 402 и ничего не списывается. Уменьшите max_results или пополните баланс.
2. Расчёт. Когда запуск завершается, списывается плата за то, что он действительно вернул, а остаток резерва возвращается на баланс.

Поиск в Google Maps с лимитом в 20 мест резервирует $0.00551. Если вернулось 14 мест, вы платите $0.004082, а $0.001428 возвращается на баланс.

Неудачные и остановленные запуски#

Неудачный запуск без результатов ничего не стоит. Каждый запуск и списание по нему видны в разделе Инструменты панели управления.

Жизненный цикл запуска#

1. 1

   Найдите инструмент

   Получите список или выполните поиск по каталогу либо опишите задачу планировщику. См. Как найти нужный инструмент.

2. 2

   Прочитайте схему входных данных

   GET /v1/tools/{id} возвращает input_schema инструмента, пример example_input и цену.

3. 3

   Запустите инструмент

   POST /v1/tools/{id}/run с вашим input и лимитом max_results. Максимальная стоимость резервируется на балансе.

4. 4

   Дождитесь результата или опрашивайте статус

   По умолчанию запрос ждёт до 60 секунд. Запуск, успевший завершиться, возвращается с кодом 200 и результатами. Более долгий запуск возвращается с кодом 202, и вы опрашиваете GET /v1/tools/runs/{run_id}, пока он не завершится.

5. 5

   Расчёт и чтение результатов

   Завершённый запуск сообщает results, charge_usd и данные в items. Запуски, которые никто не опрашивает, рассчитываются автоматически в течение нескольких минут, так что резерв никогда не зависает.

Браузерный агент#

Браузерный агент находится в том же каталоге под идентификатором browser-agent. Задайте ему цель и стартовый URL, и он выполнит задачу в настоящем браузере. Оплата идёт за шаги, а не за результаты: max_results задаёт максимальное число шагов. Полный API, включая вход в аккаунты, структурированный вывод и подтверждение человеком, описан в разделе Браузерный агент.

Ограничения#

Запуск сверх лимита одновременных запусков отклоняется с кодом 429. Запустите его снова, когда завершится другой запуск.

Что дальше#