Cara Menggunakan Cloud API untuk Browser

Tutorial ini akan memandu Anda melalui semua yang perlu Anda ketahui untuk memanfaatkan kekuatan otomatisasi browser berbasis AI. Baik Anda ingin mengotomatiskan ekstraksi data, menguji aplikasi web Anda, atau membuat alat pemantauan yang canggih, panduan ini akan memberi Anda pengetahuan dan contoh untuk memulai.

Apa Itu Browser Use Cloud?

Browser Use Cloud adalah platform canggih yang memungkinkan Anda membuat dan mengelola agen otomatisasi browser cerdas secara terprogram. Anggap saja seperti memiliki armada asisten virtual yang dapat menjelajahi web, berinteraksi dengan situs web, dan melakukan tugas-tugas kompleks atas nama Anda.

Inti dari platform ini adalah konsep "tugas" (task). Tugas adalah sekumpulan instruksi yang Anda berikan kepada agen dalam bahasa alami. Misalnya, Anda dapat memberikan tugas kepada agen seperti, "Pergi ke hacker-news.com, temukan 5 artikel teratas, dan simpan judul serta URL-nya ke dalam file." Agen kemudian akan menggunakan model bahasa besar (LLM) untuk memahami dan menjalankan instruksi ini dalam lingkungan browser nyata.

Salah satu fitur paling menarik dari Browser Use Cloud adalah umpan balik waktu nyata (real-time feedback loop). Setiap tugas yang Anda buat dilengkapi dengan live_url. URL ini menyediakan pratinjau langsung dan interaktif tentang apa yang sedang dilakukan agen. Anda dapat menyaksikan agen menjelajah secara waktu nyata dan bahkan mengambil kendali jika diperlukan. Ini membuat debugging dan pemantauan menjadi sangat intuitif.

Mendapatkan Kunci API Anda

Sebelum Anda dapat mulai membuat agen, Anda memerlukan kunci API. Kunci API mengautentikasi permintaan Anda dan menautkannya ke akun Anda.

<Note> Untuk mendapatkan kunci API Anda, Anda memerlukan langganan aktif ke Browser Use Cloud. Anda dapat mengelola langganan Anda dan mendapatkan kunci API Anda dari halaman penagihan: cloud.browser-use.com/billing. </Note>

Setelah Anda memiliki kunci API Anda, pastikan untuk menjaganya tetap aman. Perlakukan seperti kata sandi, dan jangan pernah mengeksposnya dalam kode sisi klien atau memasukkannya ke dalam kontrol versi. Sebaiknya simpan dalam variabel lingkungan yang aman.

export BROWSER_USE_API_KEY="your_api_key_here"

Memahami Model Harga

API Browser Use Cloud memiliki model harga pay-as-you-go yang sederhana. Ini memastikan bahwa Anda hanya membayar sesuai penggunaan, menjadikannya hemat biaya untuk proyek skala kecil maupun besar. Harga terdiri dari dua bagian utama:

1. Biaya Inisialisasi Tugas: Biaya tetap sebesar $0,01 dikenakan untuk setiap tugas yang Anda mulai. Ini mencakup biaya untuk menyiapkan lingkungan browser untuk agen Anda.
2. Biaya Langkah Tugas: Ini adalah biaya untuk setiap tindakan atau "langkah" yang diambil agen. Biaya per langkah tergantung pada LLM yang Anda pilih untuk menjalankan agen Anda.

Harga Langkah LLM

LLM yang berbeda memiliki kemampuan dan titik harga yang berbeda. Anda dapat memilih model yang paling sesuai dengan kebutuhan Anda untuk kinerja dan biaya. Berikut adalah rincian biaya per langkah untuk setiap model yang tersedia:

Contoh Perhitungan Biaya

Mari kita bayangkan Anda ingin mengotomatiskan tugas yang melibatkan login ke situs web, navigasi ke halaman tertentu, dan mengekstraksi beberapa data. Anda memperkirakan ini akan memakan waktu sekitar 15 langkah. Jika Anda memilih untuk menggunakan model GPT-4o yang canggih, total biaya akan dihitung sebagai berikut:

• Inisialisasi Tugas: $0,01
• Langkah Tugas: 15 langkah × $0,03/langkah = $0,45
• Total Biaya: $0,01 + $0,45 = $0,46

Harga yang transparan ini memungkinkan Anda memprediksi dan mengontrol biaya Anda secara efektif.

Membuat Agen Pertama Anda: Contoh "Hello, World!"

Sekarang bagian yang menarik! Mari kita buat agen otomatisasi browser pertama Anda. Kita akan mulai dengan tugas yang sangat sederhana: pergi ke Google dan mencari "Browser Use".

Kita akan menggunakan curl untuk membuat permintaan POST ke endpoint /api/v1/run-task. Ini adalah endpoint utama untuk membuat tugas baru.

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to google.com and search for Browser Use"
  }'

Mari kita uraikan perintah ini:

• curl -X POST ...: Kita mengirimkan permintaan HTTP POST ke URL yang ditentukan.
• H "Authorization: Bearer $BROWSER_USE_API_KEY": Ini adalah header autentikasi. Ini mencakup kunci API Anda. Kita menggunakan variabel lingkungan yang kita atur sebelumnya.
• H "Content-Type: application/json": Header ini memberi tahu API bahwa kita mengirim data dalam format JSON.
• d '{ "task": "..." }': Ini adalah badan permintaan kita. Bidang task berisi instruksi bahasa alami untuk agen kita.

Memahami Respons API

Ketika Anda mengirim permintaan ini, API akan merespons dengan objek JSON yang berisi informasi tentang tugas yang baru dibuat. Berikut adalah contoh tampilan respons tersebut:

{
  "task_id": "ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7",
  "status": "running",
  "live_url": "<https://previews.browser-use.com/ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7>"
}

• task_id: Ini adalah pengenal unik untuk tugas Anda. Anda akan menggunakan ID ini untuk mengelola tugas nanti (misalnya, untuk menjeda, melanjutkan, atau menghentikannya).
• status: Ini menunjukkan status tugas saat ini. Awalnya akan running (berjalan).
• live_url: Ini adalah URL untuk pratinjau langsung. Salin dan tempel URL ini ke browser Anda untuk melihat agen Anda beraksi!

Pratinjau Langsung Interaktif

live_url adalah salah satu fitur paling canggih dari Browser Use Cloud. Ini bukan hanya aliran video yang hanya bisa ditonton; ini adalah sesi yang sepenuhnya interaktif.

Anda dapat menyematkan live_url langsung ke dalam aplikasi Anda sendiri menggunakan iframe. Ini memungkinkan Anda membangun dasbor dan alat pemantauan kustom yang menyertakan tampilan agen Anda secara waktu nyata.

Berikut adalah cuplikan HTML sederhana untuk menyematkan pratinjau langsung:

<!DOCTYPE html>
<html>
<head>
  <title>Agent Live Preview</title>
  <style>
    body, html { margin: 0; padding: 0; height: 100%; overflow: hidden; }
    iframe { width: 100%; height: 100%; border: none; }
  </style>
</head>
<body>
  <iframe src="YOUR_LIVE_URL_HERE"></iframe>
</body>
</html>

Ganti YOUR_LIVE_URL_HERE dengan live_url dari respons API. Ketika Anda membuka file HTML ini di browser, Anda akan melihat layar agen. Anda dapat mengklik, mengetik, dan menggulir sama seperti saat Anda menjelajah di komputer Anda sendiri. Ini sangat berguna untuk:

• Debugging: Jika agen macet, Anda dapat segera melihat alasannya dan apa yang ada di layarnya.
• Intervensi Manual: Jika tugas memerlukan langkah yang sulit diotomatiskan (seperti menyelesaikan CAPTCHA yang kompleks), Anda dapat mengambil alih, menyelesaikan langkah tersebut secara manual, lalu membiarkan agen melanjutkan pekerjaannya.
• Demonstrasi: Ini adalah cara yang bagus untuk menunjukkan kepada pemangku kepentingan apa yang dilakukan otomatisasi Anda.

Mengelola Siklus Hidup Tugas

Setelah tugas berjalan, Anda memiliki kendali penuh atas siklus hidupnya. Anda dapat menjeda, melanjutkan, dan menghentikan tugas menggunakan API. Anda akan memerlukan task_id untuk semua operasi manajemen.

Menjeda dan Melanjutkan Tugas

Ada banyak alasan mengapa Anda mungkin ingin menjeda tugas. Mungkin Anda perlu memeriksa halaman web secara manual, atau mungkin Anda ingin menunggu peristiwa eksternal terjadi sebelum melanjutkan.

Untuk menjeda tugas, kirimkan permintaan POST ke endpoint /api/v1/pause-task:

curl -X POST <https://api.browser-use.com/api/v1/pause-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

Agen akan menyelesaikan langkahnya saat ini dan kemudian memasuki status paused (dijeda).

Untuk melanjutkan tugas, kirimkan permintaan POST ke endpoint /api/v1/resume-task:

curl -X POST <https://api.browser-use.com/api/v1/resume-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

Agen akan melanjutkan tepat dari titik terakhirnya.

Menghentikan Tugas

Jika Anda ingin menghentikan tugas secara permanen, Anda dapat menggunakan endpoint /api/v1/stop-task. Ini berguna jika tugas sudah selesai, mengalami kesalahan, atau tidak lagi diperlukan.

curl -X POST <https://api.browser-use.com/api/v1/stop-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

<Note> Setelah tugas dihentikan, tugas tidak dapat dilanjutkan. Lingkungan browser dihancurkan, dan semua sumber daya terkait dibersihkan. </Note>

Pembuatan Tugas Tingkat Lanjut

Contoh "Hello, World!" hanyalah permulaan. Endpoint run-task mendukung lebih dari sekadar string task sederhana. Anda dapat menyesuaikan perilaku agen Anda dengan menyediakan parameter tambahan.

Memilih LLM

Seperti yang kita lihat di bagian harga, Anda dapat memilih dari beberapa LLM yang berbeda untuk menjalankan agen Anda. Anda dapat menentukan model dalam permintaan run-task menggunakan parameter model.

Misalnya, untuk menggunakan model Claude 3.7 Sonnet, Anda akan membuat permintaan berikut:

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to reddit.com/r/programming and find the top post of the day.",
    "model": "claude-3.7-sonnet-20250219"
  }'

Jika Anda tidak menentukan model, API akan menggunakan model default, yang biasanya merupakan opsi yang hemat biaya dan berperforma tinggi seperti GPT-4o mini.

Membangun Klien Anda Sendiri

Meskipun curl bagus untuk pengujian sederhana, kemungkinan besar Anda ingin mengintegrasikan API Browser Use Cloud ke dalam aplikasi Anda menggunakan pustaka klien yang tepat. Cara terbaik untuk melakukan ini adalah menggunakan spesifikasi OpenAPI kami untuk menghasilkan klien yang type-safe.

Spesifikasi OpenAPI adalah cara standar untuk mendeskripsikan API REST. Anda dapat menemukan spesifikasi kami di sini: http://api.browser-use.com/openapi.json.

Pembuatan Klien Python

Untuk pengembang Python, kami merekomendasikan openapi-python-client. Ini menghasilkan klien modern, async-first dengan petunjuk tipe (type hints) lengkap.

Pertama, instal alat generator:

# We recommend using pipx to keep your global environment clean
pipx install openapi-python-client --include-deps

Sekarang, buat klien:

openapi-python-client generate --url <http://api.browser-use.com/openapi.json>

Ini akan membuat direktori baru yang berisi paket klien Python Anda. Anda dapat menginstalnya menggunakan pip:

pip install .

Sekarang Anda dapat menggunakan klien dalam kode Python Anda:

import asyncio
from browser_use_api import Client
from browser_use_api.models import RunTaskRequest

async def main():
    client = Client(base_url="<https://api.browser-use.com/api/v1>")
    request = RunTaskRequest(task="Go to ycombinator.com and list the top 3 companies.")

    response = await client.run_task.api_v1_run_task_post(
        client=client,
        json_body=request,
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"}
    )

    if response:
        print(f"Task created with ID: {response.task_id}")
        print(f"Live URL: {response.live_url}")

if __name__ == "__main__":
    asyncio.run(main())

Pembuatan Klien TypeScript/JavaScript

Untuk proyek frontend atau Node.js, openapi-typescript adalah alat yang sangat baik untuk menghasilkan definisi tipe TypeScript dari spesifikasi OpenAPI.

Pertama, instal generator sebagai dependensi dev:

npm install -D openapi-typescript

Kemudian, jalankan generator:

npx openapi-typescript <http://api.browser-use.com/openapi.json> -o src/browser-use-api.ts

Ini akan membuat satu file, src/browser-use-api.ts, yang berisi semua definisi tipe untuk API. Anda kemudian dapat menggunakan tipe ini dengan klien HTTP pilihan Anda, seperti fetch atau axios, untuk membuat permintaan yang type-safe.

Berikut adalah contoh menggunakan fetch dalam proyek TypeScript:

import { paths } from './src/browser-use-api';

const API_URL = "<https://api.browser-use.com/api/v1>";

type RunTaskRequest = paths["/run-task"]["post"]["requestBody"]["content"]["application/json"];
type RunTaskResponse = paths["/run-task"]["post"]["responses"]["200"]["content"]["application/json"];

async function createTask(task: string, apiKey: string): Promise<RunTaskResponse> {
  const body: RunTaskRequest = { task };

  const response = await fetch(`${API_URL}/run-task`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`API request failed with status ${response.status}`);
  }

  return response.json() as Promise<RunTaskResponse>;
}

async function run() {
  const apiKey = process.env.BROWSER_USE_API_KEY;
  if (!apiKey) {
    throw new Error("API key not found in environment variables.");
  }

  try {
    const result = await createTask("Find the current weather in New York City.", apiKey);
    console.log("Task created:", result);
  } catch (error) {
    console.error("Failed to create task:", error);
  }
}

run();