API решения капчи Прокси API Fingerprint API Browser API

Browser API: пользовательская документация

Browser API — это облачный браузер 2Captcha для автоматизации сайтов, которым нужен настоящий браузер: JavaScript-рендеринг, клики, формы, скролл, геозависимый контент, прокси и обработка CAPTCHA.

Вы подключаетесь к удаленному браузеру по готовому CDP WebSocket URL из кабинета 2Captcha и управляете им через привычные инструменты: Playwright, Puppeteer или другой клиент, который поддерживает Chrome DevTools Protocol.

Вам не нужно запускать Chrome на своем сервере, поддерживать браузерную инфраструктуру, вручную собирать прокси-строки или разбираться с форматом подключения. Все основные параметры собираются в Dashboard.

Содержание

Introduction
Quick Start
5 Minute How-To
Configuration
Features
CDP Functions
- Standard CDP / browser automation
- Custom CDP helpers
Code Examples
Troubleshooting
FAQs

Introduction

Что такое Browser API

Browser API запускает браузерную сессию в облаке 2Captcha. Ваш код подключается к этой сессии по WebSocket URL и управляет страницей так же, как если бы браузер был запущен локально.

Обычная схема работы:

Вы открываете Browser API Dashboard.
Выбираете страну и режим прокси.
Копируете готовый CDP URL.
Вставляете его в Playwright или Puppeteer.
Скрипт открывает сайт, выполняет действия и получает результат.
При необходимости вы смотрите сессию через Live.

Когда использовать Browser API

Browser API подходит, когда обычного HTTP-запроса недостаточно.

Используйте его, если сайт:

рендерит контент через JavaScript;
подгружает данные после загрузки страницы;
требует кликов, ввода текста, скролла или ожидания элементов;
показывает разные страницы в разных странах;
использует проверки, редиректы, динамические формы или CAPTCHA;
нестабильно работает при простом запросе через curl, requests, fetch или аналогичные инструменты.

Что вы получаете

С Browser API можно:

запускать удаленные браузерные сессии;
подключаться к ним через Playwright, Puppeteer и CDP-клиенты;
выбирать страну сессии;
использовать свой внешний прокси или proxy-аккаунт 2Captcha;
генерировать один CDP URL или список URL для параллельной работы;
смотреть активные сессии через Live;
решать CAPTCHA в браузерном сценарии;
отслеживать расход browser traffic.

Quick Start

Этот раздел поможет быстро запустить первую браузерную сессию.

1. Откройте Browser API Dashboard

Перейдите в раздел Browser API и откройте Dashboard.

На Dashboard находятся:

Traffic — баланс browser traffic;
Add / Buy traffic — пополнение browser traffic;
Connection setting — настройки будущего CDP URL;
CDP URL preview — готовая строка подключения;
Copy — копирование CDP URL;
Generate list — генерация списка CDP URL;
Browser Logins — текущие профили и сессии;
Live — просмотр активной браузерной сессии.

2. Проверьте browser traffic

Перед запуском убедитесь, что на балансе есть browser traffic.

Browser traffic расходуется на загрузку страниц и ресурсов внутри облачного браузера: HTML, JavaScript, CSS, изображения, шрифты, API-запросы страницы и другие сетевые запросы.

Если трафика недостаточно, нажмите Add или Buy browser traffic, выберите объем и подтвердите покупку.

Важно: browser traffic и proxy traffic — разные балансы. Browser traffic используется облачным браузером. Proxy traffic относится к proxy-сервису и оплачивается отдельно.

3. Выберите страну

В поле Country выберите страну, из которой должна работать сессия.

Например:

text Copy

de — Германия
us — США
fr — Франция

Выбранная страна будет использована в CDP URL. Если выбран proxy-аккаунт 2Captcha, эта же страна будет применена и к proxy-сессии.

4. Выберите режим прокси

Доступны два основных режима.

Custom proxy — используйте, если у вас есть внешний прокси и вы хотите ввести его вручную.

Proxy account — используйте, если хотите выбрать proxy-аккаунт из кабинета 2Captcha. В этом режиме host, port, login и password подставляются автоматически.

5. Скопируйте CDP URL

После выбора настроек Dashboard сразу показывает готовый CDP URL.

Нажмите Copy и вставьте URL в код.

Пример вида CDP URL:

text Copy

ws://10001-pid-profilea3f9k-zone-country-de-proxy-...:cloud_browser_pass@cb.2captcha.com:9222

CDP URL содержит данные доступа к браузеру, поэтому храните его как секрет: не публикуйте в репозиториях, логах, тикетах и чатах.

6. Подключитесь из кода

Пример на Python + Playwright:

python Copy

import asyncio
from playwright.async_api import async_playwright

CDP_URL = "ws://..."  # вставьте CDP URL из Dashboard
TARGET_URL = "https://example.com"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        page = await browser.new_page()

        await page.goto(TARGET_URL, timeout=120_000)
        print(await page.title())

        await browser.close()

asyncio.run(main())

Если скрипт подключился к браузеру, открыл страницу и вывел заголовок — Browser API работает.

5 Minute How-To

Сценарий для проверки Browser API за несколько минут.

Что нужно перед началом

Убедитесь, что у вас есть:

аккаунт 2Captcha;
доступ к разделу Browser API;
browser traffic на балансе;
установленный Playwright или Puppeteer;
тестовый URL, который нужно открыть.

Шаг 1. Выберите тестовую страницу

Для первого запуска лучше взять страницу, которая точно открывается в браузере.

Примеры задач для проверки:

получить title страницы;
дождаться появления элемента;
сделать скриншот;
получить HTML после выполнения JavaScript.

Шаг 2. Сгенерируйте CDP URL

В Dashboard выберите:

Country;
режим прокси: Custom proxy или Proxy account;
нужный proxy-аккаунт или данные внешнего прокси.

Скопируйте CDP URL через Copy.

Шаг 3. Запустите скрипт

Вставьте CDP URL в пример Playwright или Puppeteer и запустите код.

Используйте timeout не меньше 120 секунд, потому что некоторые сайты долго загружаются из-за JavaScript, редиректов, проверок и тяжелых ресурсов.

Шаг 4. Проверьте результат

Успешная проверка означает, что скрипт:

подключился к облачному браузеру;
открыл новую страницу;
перешел на target URL;
дождался загрузки;
получил title, HTML или скриншот;
закрыл браузер после завершения.

Шаг 5. Откройте Live при ошибке

Если скрипт завис, страница пустая или элемент не найден, нажмите Live рядом с нужным профилем.

Live показывает, что реально видит облачный браузер: страницу, редирект, форму, CAPTCHA, ошибку загрузки или нужный контент.

Configuration

Раздел Configuration описывает настройки, которые пользователь выбирает перед запуском браузерной сессии.

Dashboard

Dashboard — основная страница Browser API. Здесь пользователь готовит подключение и контролирует активные сессии.

На Dashboard можно:

проверить баланс browser traffic;
пополнить browser traffic;
выбрать страну сессии;
выбрать режим прокси;
сгенерировать CDP URL;
скопировать один URL;
сгенерировать список URL;
открыть активную сессию через Live;
посмотреть активные browser profiles, время работы и расход трафика.

CDP URL Generator

CDP URL Generator собирает строку подключения автоматически. Пользователю не нужно вручную кодировать прокси, генерировать profile ID или проверять формат WebSocket URL.

Генератор обновляет preview при любом изменении формы.

Основной формат CDP URL:

text Copy

ws://{user_id}-pid-{profile_id}-zone-country-{country_code}-proxy-{proxy_base64url}:{password}@cb.2captcha.com:9222

Что важно пользователю:

user_id подставляется автоматически;
profile_id создается автоматически;
country_code берется из dropdown Country;
proxy_base64url формируется из выбранного прокси;
password подставляется сервисом;
готовый URL нужно копировать через Copy.

Обычно редактировать CDP URL вручную не нужно.

Режим Custom proxy

Режим Custom proxy нужен, если вы хотите использовать свой внешний прокси.

Поля формы:

Country — страна сессии;
Protocol — http, https или socks5;
Host — адрес прокси;
Port — порт прокси;
Login — логин прокси, если требуется;
Password — пароль прокси, если требуется.

Если прокси не требует авторизации, оставьте Login и Password пустыми.

Dashboard соберет proxy URL и добавит его в CDP URL.

Формат прокси с авторизацией:

text Copy

{protocol}://{login}:{password}@{host}:{port}

Формат прокси без авторизации:

text Copy

{protocol}://{host}:{port}

Пример:

text Copy

http://myuser:mypass@proxy.example.com:8080

После выбора страны и прокси итоговый CDP URL будет выглядеть так:

text Copy

ws://10001-pid-profilea3f9k-zone-country-de-proxy-aHR0cDovL215dXNlcjpteXBhc3NAcHJveHkuZXhhbXBsZS5jb206ODA4MA:cloud_browser_pass@cb.2captcha.com:9222

Custom proxy применяется к сессиям, запущенным по конкретному CDP URL. Он не сохраняется как постоянная настройка профиля.

Режим Proxy account

Режим Proxy account нужен, если вы хотите использовать proxy-аккаунт из кабинета 2Captcha.

Поля формы:

Proxy account — proxy-аккаунт из списка;
Country — страна сессии.

В этом режиме не нужно вводить host, port, login и password. Dashboard получает данные proxy-аккаунта и формирует CDP URL автоматически.

Для proxy-сессии создается отдельный session ID. Это помогает разделять сессии и не смешивать параллельные запуски.

Время proxy-сессии — 30 минут.

Пример proxy URL до добавления в CDP URL:

text Copy

http://proxy_username-zone-custom-region-de-session-KSZIcwVJd-sessTime-30:proxy_password@eu.proxy.2captcha.com:2334

Пример итогового CDP URL:

text Copy

ws://10001-pid-profilem8z1q-zone-country-de-proxy-aHR0cDovL3Byb3h5X3VzZXJuYW1lLXpvbmUtY3VzdG9tLXJlZ2lvbi1kZS1zZXNzaW9uLUtTWkljd1ZKZC1zZXNzVGltZS0zMDpwcm94eV9wYXNzd29yZEBldS5wcm94eS4yY2FwdGNoYS5jb206MjMzNA:cloud_browser_pass@cb.2captcha.com:9222

Country

Country задает географию браузерной сессии.

Страна используется в двух местах:

в CDP URL: zone-country-{country_code};
в режиме Proxy account: в proxy-логине как region-{country_code}.

Значения всегда совпадают. Если выбрана Германия, браузерная сессия и proxy-сессия используют de. Если выбраны США — us.

Выбирайте country перед копированием CDP URL. Если вы изменили country после копирования, скопируйте URL заново.

Generate list

Generate list нужен, если вы хотите создать несколько CDP URL сразу.

Используйте его для:

параллельных воркеров;
очередей задач;
независимых браузерных сессий;
запуска нескольких сценариев с одной страной;
массовой проверки страниц;
подготовки URL для разных процессов или серверов.

Как пользоваться:

Настройте Country и режим прокси.
Нажмите Generate list.
Укажите количество URL.
Нажмите Generate.
Скопируйте список через Copy all.

Каждый URL выводится с новой строки.

В режиме Custom proxy каждый URL получает новый profile ID, но использует один и тот же прокси.

В режиме Proxy account каждый URL получает новый profile ID и новый session ID.

Не используйте один и тот же CDP URL для нескольких независимых параллельных задач. Если каждой задаче нужна отдельная сессия, сгенерируйте список.

Browser Logins

Browser profile — это профиль браузерной сессии.

В таблице Browser Logins отображаются:

CDP URL — строка подключения;
Copy — копирование CDP URL;
Live — просмотр активной сессии;
Created At — время запуска;
Duration — сколько работает сессия;
Traffic — расход browser traffic по сессии.

Если достигнут лимит активных профилей, отключите или удалите ненужные профили и создайте новый.

Traffic

Browser traffic — это трафик, который расходует облачный браузер.

Трафик общий для всех browser profiles в аккаунте. Он не закрепляется за конкретным профилем.

На Dashboard отображается текущий баланс. В разделе Statistics можно посмотреть расход по периоду и по профилям.

Чтобы снизить расход трафика:

закрывайте браузер после завершения сценария;
не открывайте лишние вкладки;
избегайте повторных переходов без необходимости;
блокируйте тяжелые ресурсы, если они не нужны для задачи;
используйте Generate list только для действительно независимых сессий.

Features

Captcha Solver

Browser API помогает работать со страницами, на которых появляется CAPTCHA.

В типовом сценарии вы запускаете браузерную сессию, открываете страницу и продолжаете работу после прохождения проверки. Если CAPTCHA появляется во время сценария, ее можно отслеживать через Live и через CDP-команды.

Когда это полезно:

форма или страница открывается только после CAPTCHA;
CAPTCHA появляется не сразу, а после клика или отправки формы;
нужно автоматизировать сценарий без ручного вмешательства;
нужно увидеть статус решения в коде.

Пример проверки статуса через CDP helper:

javascript Copy

const client = await page.target().createCDPSession();
const { status } = await client.send('Captcha.solve', { detectTimeout: 30000 });
console.log(`Captcha status: ${status}`);

Если сценарий не проходит дальше, откройте Live и проверьте, на каком шаге находится браузер.

Geolocation targeting

Geolocation targeting позволяет запускать сессии из нужной страны.

Это нужно, если сайт:

показывает разные цены по странам;
меняет язык или валюту;
открывает разные версии страниц;
ограничивает доступ по региону;
требует проверки доступности контента из конкретной страны.

В Dashboard выберите Country. Код страны автоматически попадет в CDP URL.

Пример фрагмента CDP URL для Германии:

text Copy

zone-country-de

В режиме Proxy account эта же страна используется в proxy-сессии:

text Copy

region-de

Playground

Playground — это место для быстрой проверки Browser API без настройки полноценного проекта.

Используйте Playground, чтобы:

запустить готовый пример;
проверить CDP URL;
открыть тестовую страницу;
посмотреть результат без долгой настройки окружения;
быстро понять, работает ли страна, прокси и сессия.

После успешной проверки перенесите тот же CDP URL и сценарий в свой код.

Live debugging

Live debugging позволяет смотреть активную браузерную сессию в браузере.

Открывайте Live, когда нужно понять:

загрузилась ли страница;
видит ли браузер нужный контент;
появилась ли CAPTCHA;
сработал ли клик;
куда произошел редирект;
почему элемент не найден;
какая страна или прокси применились.

Live не заменяет код автоматизации, но сильно ускоряет отладку.

Parallel sessions

Browser API поддерживает параллельные независимые сессии.

Для параллельного запуска используйте Generate list. Каждый URL из списка можно передать отдельному воркеру или процессу.

Рекомендации:

один CDP URL — одна независимая браузерная сессия;
для нескольких задач генерируйте несколько URL;
не переиспользуйте один и тот же URL в разных воркерах одновременно;
следите за лимитом активных профилей и расходом traffic.

CDP Functions

Standard CDP / browser automation

После подключения по CDP URL вы можете использовать обычные команды Playwright или Puppeteer.

Частые действия:

открыть страницу;
дождаться селектора;
кликнуть по элементу;
заполнить поле;
выполнить JavaScript на странице;
получить HTML;
сделать скриншот;
перехватывать запросы;
работать с cookies;
закрыть браузер.

Примеры:

javascript Copy

await page.goto('https://example.com', { timeout: 120000 });
await page.waitForSelector('body', { timeout: 30000 });
console.log(await page.title());

python Copy

await page.goto('https://example.com', timeout=120_000)
await page.wait_for_selector('body', timeout=30_000)
print(await page.title())

Custom CDP helpers

Custom helpers используются для функций Browser API, которые удобнее вызывать через CDP.

Типичные примеры:

получить ссылку на инспекцию активной сессии;
проверить или запустить решение CAPTCHA;
получить служебную информацию по сессии;
управлять дополнительными настройками браузерной сессии.

Пример открытия inspect-ссылки через CDP:

javascript Copy

const client = await page.target().createCDPSession();
const { frameTree: { frame } } = await client.send('Page.getFrameTree');
const { url } = await client.send('Page.inspect', { frameId: frame.id });
console.log(`Inspect session: ${url}`);

Если для задачи достаточно обычного Playwright или Puppeteer API, custom helpers использовать не обязательно.

Code Examples

Playwright Python

python Copy

import asyncio
from playwright.async_api import async_playwright

CDP_URL = "ws://..."  # скопируйте из Browser API Dashboard
TARGET_URL = "https://example.com"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        page = await browser.new_page()

        await page.goto(TARGET_URL, timeout=120_000)
        await page.wait_for_selector("body", timeout=30_000)

        print("Title:", await page.title())
        html = await page.content()
        print("HTML length:", len(html))

        await page.screenshot(path="page.png", full_page=True)
        await browser.close()

asyncio.run(main())

Puppeteer Node.js

javascript Copy

const puppeteer = require('puppeteer-core');

const CDP_URL = 'ws://...'; // скопируйте из Browser API Dashboard
const TARGET_URL = 'https://example.com';

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: CDP_URL,
  });

  try {
    const page = await browser.newPage();
    await page.goto(TARGET_URL, { timeout: 120000 });
    await page.waitForSelector('body', { timeout: 30000 });

    console.log('Title:', await page.title());
    console.log('HTML length:', (await page.content()).length);

    await page.screenshot({ path: 'page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

Работа со списком CDP URL

Если вы сгенерировали список URL через Generate list, передайте каждый URL отдельному воркеру.

Пример идеи на Node.js:

javascript Copy

const puppeteer = require('puppeteer-core');

const CDP_URLS = [
  'ws://...',
  'ws://...',
  'ws://...',
];

async function runJob(cdpUrl, targetUrl) {
  const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl });

  try {
    const page = await browser.newPage();
    await page.goto(targetUrl, { timeout: 120000 });
    return await page.title();
  } finally {
    await browser.close();
  }
}

(async () => {
  const results = await Promise.all(
    CDP_URLS.map((url, index) => runJob(url, `https://example.com/?job=${index}`))
  );

  console.log(results);
})();

Troubleshooting

Не получается подключиться к браузеру

Проверьте:

CDP URL скопирован полностью;
URL начинается с ws://;
host — cb.2captcha.com;
port — 9222;
на балансе есть browser traffic;
сеть не блокирует WebSocket-подключения;
в Playwright используется connect_over_cdp;
в Puppeteer используется puppeteer.connect, а не puppeteer.launch.

Ошибка авторизации

Скопируйте CDP URL заново из Dashboard.

Не используйте старый URL, если менялись:

country;
proxy mode;
proxy account;
custom proxy;
profile ID;
сервисный пароль.

Custom proxy не работает

Проверьте:

protocol выбран правильно;
host указан без http:// и без порта;
port указан отдельно;
login и password заполнены только если прокси требует авторизацию;
прокси доступен извне;
прокси поддерживает выбранный protocol;
после изменения формы CDP URL скопирован заново.

Страна не применилась

Измените Country и скопируйте новый CDP URL.

Если используется Generate list, после изменения страны нажмите Generate заново.

Страница долго загружается

Установите timeout 120 секунд или больше.

Также откройте Live, чтобы понять, что происходит в браузере: идет загрузка, редирект, CAPTCHA, ошибка сайта или ожидание ресурса.

Быстро расходуется traffic

Проверьте, не загружает ли сценарий много изображений, видео, шрифтов или лишних страниц.

Для экономии можно блокировать тяжелые ресурсы.

Пример для Puppeteer:

javascript Copy

await page.setRequestInterception(true);

page.on('request', request => {
  const type = request.resourceType();

  if (['image', 'media', 'font'].includes(type)) {
    request.abort();
  } else {
    request.continue();
  }
});

Элемент не найден

Возможные причины:

страница еще не успела отрендериться;
нужен другой селектор;
элемент появляется после клика или скролла;
сайт показал CAPTCHA или редирект;
target URL открыл другую региональную версию страницы.

Откройте Live и проверьте фактическое состояние страницы.

FAQs

Нужно ли устанавливать Chrome на сервер?

Нет. Браузер запускается в облаке 2Captcha. На вашей стороне нужен только код и библиотека автоматизации.

Можно ли использовать Playwright?

Да. Используйте chromium.connect_over_cdp(CDP_URL).

Можно ли использовать Puppeteer?

Да. Используйте puppeteer.connect({ browserWSEndpoint: CDP_URL }).

Можно ли использовать один CDP URL много раз?

Для независимых параллельных задач лучше генерировать отдельный CDP URL на каждую сессию. Для этого используйте Generate list.

Чем Custom proxy отличается от Proxy account?

Custom proxy — это внешний прокси, который вы вводите вручную.

Proxy account — это прокси из кабинета 2Captcha, который выбирается из списка и подставляется автоматически.

Можно ли использовать прокси без логина и пароля?

Да. В режиме Custom proxy оставьте Login и Password пустыми. Тогда proxy URL будет сформирован в формате:

text Copy

{protocol}://{host}:{port}

Что делает Country?

Country задает страну браузерной сессии. В режиме Proxy account эта же страна используется для proxy-сессии.

Что делает Refresh?

Refresh создает новый profile ID и обновляет одиночный CDP URL.

Что делает Generate list?

Generate list создает несколько CDP URL. Каждый URL предназначен для отдельной браузерной сессии.

Что такое profile ID?

Profile ID — это идентификатор браузерной сессии. Он создается автоматически и входит в CDP URL.

Пример:

text Copy

profilea3f9k

Откройте Browser API Dashboard.
Проверьте browser traffic.
Выберите Country.
Выберите Custom proxy или Proxy account.
Скопируйте CDP URL через Copy.
Подключитесь через Playwright или Puppeteer.
Установите timeout 120 секунд.
Дождитесь нужного элемента или получите HTML.
Закройте браузер через browser.close().
При ошибке откройте Live.

UI Update (Cloud Browser Dashboard)

Browser Logins

Browser Login является основной сущностью Cloud Browser.

Для каждого логина отображаются:

CDP URL;
Created At;
Duration;
Traffic;
Active Profiles;
Live;
Generate Profiles;
Flush Profiles.

В верхней части таблицы отображается текущий лимит логинов:

Copy

Logins 3/10

Кнопка + Add открывает окно создания нового логина.

Active Profiles

Показывает количество активных профилей и максимальный лимит.

Пример:

Copy

23/1000

Flush Profiles

Удаляет все профили выбранного логина.

Перед удалением отображается подтверждение:

Copy

All profile data will be permanently deleted.
Are you sure?

Proxy Information

Для сервисных прокси отображается:

Copy

account_id + proxy URL

Для пользовательских прокси:

Copy

login + proxy URL

Вариант "No proxy attached" больше не используется.

Для создания логина нажмите + Add.

Visible name

Отображаемое имя логина.

Password

По умолчанию пароль генерируется автоматически.

Для задания собственного пароля:

Включите Set custom password.
Укажите пароль.

Поддерживаются варианты:

2Captcha account

выбор аккаунта;
выбор региона.

Custom

protocol;
host;
port;
login;
password.

Generate Profile URLs

Кнопка Generate Profiles открывает окно генерации профилей.

Count

Количество URL для генерации.

Максимум рассчитывается автоматически:

Copy

1000 - Active Profiles

Пример:

Copy

max 977 (1000 - 23 active)

Для каждого профиля отображаются:

Profile ID;
дата создания;
последняя активность;
расход трафика;
статус.

Browser API

Браузерные отпечатки

Unlocker APIСкоро

Каталог программ

Блог

How-to

Демо капч