브라우저 클라우드 API 사용법

이 튜토리얼은 AI 기반 브라우저 자동화의 힘을 활용하기 위해 알아야 할 모든 것을 안내합니다. 데이터 추출을 자동화하든, 웹 애플리케이션을 테스트하든, 정교한 모니터링 도구를 만들든, 이 가이드가 시작하는 데 필요한 지식과 예시를 제공할 것입니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

최대 생산성으로 개발 팀이 함께 작업할 수 있는 통합 올인원 플랫폼을 원하십니까?

Apidog는 귀하의 모든 요구 사항을 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!

버튼

Browser Use Cloud란 무엇인가요?

Browser Use Cloud는 지능형 브라우저 자동화 에이전트를 프로그래밍 방식으로 생성하고 관리할 수 있는 강력한 플랫폼입니다. 웹을 탐색하고, 웹사이트와 상호 작용하며, 사용자를 대신하여 복잡한 작업을 수행할 수 있는 가상 비서 집합을 갖는다고 생각하면 됩니다.

플랫폼의 핵심은 '작업(task)'이라는 개념입니다. 작업은 자연어로 에이전트에게 제공하는 일련의 지침입니다. 예를 들어, 에이전트에게 "hacker-news.com으로 이동하여 상위 5개 기사를 찾고 해당 제목과 URL을 파일에 저장하라"는 작업을 줄 수 있습니다. 그러면 에이전트는 대규모 언어 모델(LLM)을 사용하여 실제 브라우저 환경에서 이러한 지침을 이해하고 실행합니다.

Browser Use Cloud의 가장 흥미로운 기능 중 하나는 실시간 피드백 루프입니다. 생성하는 모든 작업에는 live_url이 함께 제공됩니다. 이 URL은 에이전트가 수행하는 작업에 대한 실시간 대화형 미리보기를 제공합니다. 에이전트가 실시간으로 탐색하는 것을 볼 수 있으며 필요하면 제어권을 가져올 수도 있습니다. 이를 통해 디버깅 및 모니터링이 매우 직관적입니다.

API 키 가져오기

에이전트 생성을 시작하기 전에 API 키가 필요합니다. API 키는 요청을 인증하고 계정에 연결합니다.

<참고> API 키를 얻으려면 Browser Use Cloud 활성 구독이 필요합니다. 구독을 관리하고 결제 페이지(cloud.browser-use.com/billing)에서 API 키를 얻을 수 있습니다. </참고>

API 키를 얻으면 안전하게 보관하십시오. 비밀번호처럼 취급하고 클라이언트 측 코드에 노출하거나 버전 제어에 커밋하지 마십시오. 안전한 환경 변수에 저장하는 것이 가장 좋습니다.

export BROWSER_USE_API_KEY="your_api_key_here"

가격 모델 이해하기

Browser Use Cloud API는 간단한 종량제 가격 모델을 사용합니다. 이를 통해 사용한 만큼만 지불하여 소규모 프로젝트와 대규모 프로젝트 모두에 비용 효율적입니다. 가격은 두 가지 주요 부분으로 구성됩니다.

작업 초기화 비용: 시작하는 모든 작업에 대해 $0.01의 고정 요금이 부과됩니다. 이는 에이전트의 브라우저 환경을 시작하는 비용을 포함합니다.
작업 단계 비용: 이는 에이전트가 수행하는 각 작업 또는 '단계'에 대한 비용입니다. 단계당 비용은 에이전트를 구동하기 위해 선택한 LLM에 따라 다릅니다.

LLM 단계별 가격

다양한 LLM은 서로 다른 기능과 가격대를 가지고 있습니다. 성능 및 비용에 가장 적합한 모델을 선택할 수 있습니다. 사용 가능한 각 모델의 단계당 비용 분석은 다음과 같습니다.

모델	단계당 비용
GPT-4o	$0.03
GPT-4.1	$0.03
Claude 3.7 Sonnet (2025-02-19)	$0.03
GPT-4o mini	$0.01
GPT-4.1 mini	$0.01
Gemini 2.0 Flash	$0.01
Gemini 2.0 Flash Lite	$0.01
Llama 4 Maverick	$0.01

비용 계산 예시

웹사이트에 로그인하고, 특정 페이지로 이동하고, 일부 데이터를 추출하는 작업을 자동화한다고 상상해 봅시다. 이 작업은 약 15단계가 소요될 것으로 예상됩니다. 강력한 GPT-4o 모델을 사용하기로 선택한 경우 총 비용은 다음과 같이 계산됩니다.

작업 초기화: $0.01
작업 단계: 15단계 × 단계당 $0.03 = $0.45
총 비용: $0.01 + $0.45 = $0.46

이 투명한 가격 책정을 통해 비용을 효과적으로 예측하고 제어할 수 있습니다.

첫 번째 에이전트 생성: 'Hello, World!' 예시

이제 흥미로운 부분입니다! 첫 번째 브라우저 자동화 에이전트를 만들어 봅시다. Google로 이동하여 'Browser Use'를 검색하는 매우 간단한 작업부터 시작하겠습니다.

curl을 사용하여 /api/v1/run-task 엔드포인트에 POST 요청을 보낼 것입니다. 이는 새 작업을 생성하기 위한 기본 엔드포인트입니다.

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"
  }'

이 명령어를 분석해 봅시다.

curl -X POST ...: 지정된 URL로 HTTP POST 요청을 보냅니다.
H "Authorization: Bearer $BROWSER_USE_API_KEY": 이는 인증 헤더입니다. API 키를 포함합니다. 이전에 설정한 환경 변수를 사용합니다.
H "Content-Type: application/json": 이 헤더는 API에 JSON 형식으로 데이터를 보내고 있음을 알려줍니다.
d '{ "task": "..." }': 이는 요청 본문입니다. task 필드는 에이전트에 대한 자연어 지침을 포함합니다.

API 응답 이해하기

이 요청을 보내면 API는 새로 생성된 작업에 대한 정보가 포함된 JSON 객체로 응답합니다. 응답 예시는 다음과 같습니다.

{
  "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: 이는 작업의 고유 식별자입니다. 이 ID를 사용하여 나중에 작업을 관리합니다(예: 일시 중지, 재개 또는 중지).
status: 이는 작업의 현재 상태를 나타냅니다. 초기에는 running 상태가 됩니다.
live_url: 이는 라이브 미리보기 URL입니다. 이 URL을 브라우저에 복사하여 붙여넣어 에이전트가 작동하는 모습을 확인하세요!

대화형 라이브 미리보기

live_url은 Browser Use Cloud의 가장 강력한 기능 중 하나입니다. 단순히 읽기 전용 비디오 스트림이 아니라 완전히 대화형 세션입니다.

iframe을 사용하여 live_url을 자신의 애플리케이션에 직접 포함할 수 있습니다. 이를 통해 에이전트의 실시간 보기를 포함하는 사용자 지정 대시보드 및 모니터링 도구를 구축할 수 있습니다.

다음은 라이브 미리보기를 포함하는 간단한 HTML 코드 조각입니다.

<!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>

YOUR_LIVE_URL_HERE를 API 응답의 live_url로 바꿉니다. 브라우저에서 이 HTML 파일을 열면 에이전트의 화면을 볼 수 있습니다. 마치 자신의 컴퓨터에서 탐색하는 것처럼 클릭하고, 입력하고, 스크롤할 수 있습니다. 이는 다음 상황에서 매우 유용합니다.

디버깅: 에이전트가 멈춘 경우, 즉시 이유와 화면 내용을 확인할 수 있습니다.
수동 개입: 작업에 자동화하기 어려운 단계(예: 복잡한 CAPTCHA 해결)가 필요한 경우, 제어권을 가져와 수동으로 단계를 완료한 다음 에이전트가 작업을 재개하도록 할 수 있습니다.
데모: 이해 관계자에게 자동화가 무엇을 하고 있는지 보여주기에 좋은 방법입니다.

작업 수명 주기 관리

작업이 실행되면 해당 수명 주기를 완벽하게 제어할 수 있습니다. API를 사용하여 작업을 일시 중지, 재개 및 중지할 수 있습니다. 모든 관리 작업에는 task_id가 필요합니다.

작업 일시 중지 및 재개

작업을 일시 중지하려는 여러 가지 이유가 있을 수 있습니다. 웹 페이지를 수동으로 검사해야 하거나, 계속하기 전에 외부 이벤트가 발생하기를 기다려야 할 수도 있습니다.

작업을 일시 중지하려면 /api/v1/pause-task 엔드포인트에 POST 요청을 보냅니다.

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"
  }'

에이전트는 현재 단계를 완료한 다음 paused 상태로 전환됩니다.

작업을 재개하려면 /api/v1/resume-task 엔드포인트에 POST 요청을 보냅니다.

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"
  }'

에이전트는 중단된 지점에서 바로 다시 시작합니다.

작업 중지

작업을 영구적으로 종료하려면 /api/v1/stop-task 엔드포인트를 사용할 수 있습니다. 작업이 완료되었거나, 잘못되었거나, 더 이상 필요하지 않은 경우에 유용합니다.

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"
  }'

<참고> 작업이 중지되면 다시 재개할 수 없습니다. 브라우저 환경은 파괴되고 관련 리소스는 모두 정리됩니다. </참고>

고급 작업 생성

'Hello, World!' 예시는 시작에 불과했습니다. run-task 엔드포인트는 단순한 task 문자열 이상의 것을 지원합니다. 추가 매개변수를 제공하여 에이전트의 동작을 사용자 지정할 수 있습니다.

LLM 선택

가격 섹션에서 보았듯이, 에이전트를 구동하기 위해 여러 다른 LLM 중에서 선택할 수 있습니다. run-task 요청에서 model 매개변수를 사용하여 모델을 지정할 수 있습니다.

예를 들어, Claude 3.7 Sonnet 모델을 사용하려면 다음 요청을 수행합니다.

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"
  }'

모델을 지정하지 않으면 API는 일반적으로 GPT-4o mini와 같은 비용 효율적이고 성능이 좋은 기본 모델을 사용합니다.

자체 클라이언트 구축

curl은 간단한 테스트에 유용하지만, 적절한 클라이언트 라이브러리를 사용하여 Browser Use Cloud API를 애플리케이션에 통합하고 싶을 것입니다. 이를 위한 가장 좋은 방법은 OpenAPI 사양을 사용하여 타입 안전(type-safe) 클라이언트를 생성하는 것입니다.

OpenAPI 사양은 REST API를 설명하는 표준화된 방법입니다. 사양은 여기에서 찾을 수 있습니다: http://api.browser-use.com/openapi.json.

Python 클라이언트 생성

Python 개발자의 경우 openapi-python-client를 추천합니다. 전체 타입 힌트가 포함된 최신 비동기 우선 클라이언트를 생성합니다.

먼저 생성기 도구를 설치합니다.

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

이제 클라이언트를 생성합니다.

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

이렇게 하면 Python 클라이언트 패키지를 포함하는 새 디렉토리가 생성됩니다. pip를 사용하여 설치할 수 있습니다.

pip install .

이제 Python 코드에서 클라이언트를 사용할 수 있습니다.

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())

TypeScript/JavaScript 클라이언트 생성

프론트엔드 또는 Node.js 프로젝트의 경우 openapi-typescript는 OpenAPI 사양에서 TypeScript 타입 정의를 생성하는 훌륭한 도구입니다.

먼저 개발 종속성으로 생성기를 설치합니다.

npm install -D openapi-typescript

그런 다음 생성기를 실행합니다.

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

이렇게 하면 API에 대한 모든 타입 정의가 포함된 단일 파일 src/browser-use-api.ts가 생성됩니다. 그런 다음 fetch 또는 axios와 같은 선호하는 HTTP 클라이언트와 함께 이러한 타입을 사용하여 타입 안전 요청을 할 수 있습니다.

다음은 TypeScript 프로젝트에서 fetch를 사용하는 예시입니다.

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();

💡

버튼