Документация API Ceki.me

Арендуйте реальные браузерные сессии через MCP, Python SDK, JavaScript SDK или REST API

Быстрый старт

Два способа начать работу с Ceki — выберите подходящий.

Путь A — Саморегистрация агента через MCP

Позвольте вашему AI-агенту зарегистрироваться самостоятельно без ручной настройки.

1. Добавьте MCP-конфиг (без авторизации)

JSON
{
  "mcpServers": {
    "ceki": {
      "url": "https://api.ceki.me/mcp/agent"
    }
  }
}

2. Попросите агента зарегистрироваться

Prompt
"Зарегистрируй меня как Ceki-агента. Имя: my-agent. Email: you@example.com"

3. Агент вызывает register-agent

Бэкенд возвращает api_key в ответе и отправляет 6-значный код подтверждения на указанный email.

4. Подтвердите email

Prompt
"Подтверди мой email кодом 123456"

5. Переподключите MCP с авторизацией

JSON
{
  "mcpServers": {
    "ceki": {
      "url": "https://api.ceki.me/mcp/agent",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

6. Пополните кошелёк

Спросите агента: «Покажи мой кошелёк» (вызовет get-wallet). Переведите крипту на wallet.deposit_address из ответа.

7. Готово

Статус становится active — все инструменты доступны. Начинайте арендовать браузеры.

Путь B — Вручную через Dashboard

Зарегистрируйтесь через веб-интерфейс и создайте ключ агента.

  1. Зарегистрируйтесь на ceki.me (email + пароль + OTP)
  2. Откройте Dashboard → Agents
  3. Нажмите Create Agent, заполните форму, скопируйте api_key из диалога (показывается один раз)
  4. Добавьте ключ в MCP-конфиг (Authorization: Bearer ag_...)
  5. Переведите крипту на адрес кошелька в Dashboard — статус станет active
JSON
{
  "mcpServers": {
    "ceki": {
      "url": "https://api.ceki.me/mcp/agent",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Python SDK

Установите SDK и арендуйте сессию в несколько строк:

bash
pip install ceki-sdk
Python
import asyncio
import os
from ceki_browser import connect

async def main():
    client = await connect(os.environ["CEKI_API_KEY"])
    options = await client.search({"geo": "DE", "language": "en"})
    browser = await client.rent(options[0].schedule_id)

    await browser.navigate("https://example.com")
    snap = await browser.snapshot()
    print(snap.title)

    await browser.close()
    await client.close()

asyncio.run(main())

JavaScript SDK

Работает с Node.js 18+ и современными браузерами.

bash
npm install @ceki/sdk
JavaScript
import { connect } from '@ceki/sdk';

const client = await connect(process.env.CEKI_API_KEY);
const options = await client.search({ geo: 'DE', language: 'en' });
const browser = await client.rent(options[0].schedule_id);

await browser.navigate('https://example.com');
const snap = await browser.snapshot();
console.log(snap.title);

await browser.close();
await client.close();

Командная строка

Оба SDK ставят один и тот же CLI ceki в PATH. Команды идентичны — выбирай способ установки под свой стек.

Установка

Python:

bash
pip install ceki-sdk

Node.js:

bash
npm install -g @ceki/sdk

После установки запусти ceki --help чтобы убедиться что бинарь в PATH.

Переменные окружения

Конфигурация через env, не через флаги. Положи в свой shell или .env:

ПеременнаяОбязательнаяНазначение
CEKI_API_KEYдаAgent-токен (ag_...). Получи через MCP-tool register-agent (рекомендуется для агентов) или в Dashboard → Agents → Create Agent.
CEKI_API_URLнетПереопределить базовый URL API. По умолчанию: https://api.ceki.me.
CEKI_RELAY_URLнетПереопределить WebSocket relay браузера. По умолчанию: wss://browser.ceki.me/ws/agent.
CEKI_CHAT_URLнетПереопределить URL chat-сервиса.
CEKI_BASIC_AUTH_USERнетHTTP Basic Auth логин (только для защищённых dev/stage endpoints).
CEKI_BASIC_AUTH_PASSнетHTTP Basic Auth пароль (только для защищённых dev/stage endpoints).

Быстрый старт

Пять команд: арендовать, управлять, закрыть:

bash
export CEKI_API_KEY=ag_...

SCHEDULE=$(ceki search --limit 1 | jq -r '.[0].schedule_id')
SID=$(ceki rent --schedule $SCHEDULE | jq -r .session_id)
ceki navigate $SID https://example.com
ceki snapshot $SID -o snap.png
ceki stop $SID

CLI сохраняет состояние сессии локально — после rent запоминает session_id, чтобы последующие команды резюмили её по SID без повторной аренды.

Команды

Поиск и жизненный цикл

КомандаЧто делает
search [--limit N] [--filter K=V]…Список доступных браузеров. Фильтры: страна, время, цена и т.д.
my-browsersСписок браузеров с заранее согласованным контрактом.
rent --schedule ID [--mode incognito|main] [--fingerprint-from FILE]Арендовать браузер по schedule_id. --mode main запрашивает реальный профиль владельца (должен быть pre-authorized).
sessions [--all] [--limit N] [--json]Список твоих сессий. По умолчанию только активные; --all покажет завершённые.
stop SIDЗакрыть сессию (освобождает браузер и останавливает биллинг).
wait SIDБлокироваться до завершения сессии. Удобно в скриптах для cleanup по истечении.

Управление браузером

КомандаЧто делает
navigate SID URLОткрыть URL в арендованном браузере.
click SID X YКлик по координатам viewport (X, Y в пикселях).
type SID TEXT [--natural]Печать текста в активный элемент. --natural добавляет человекоподобные задержки.
scroll SID X Y DYПрокрутка из точки (X, Y) на DY пикселей (отрицательный = вниз).
screenshot SID -o FILE [--format png|jpeg] [--full]Снимок viewport (или --full страницы) в файл.
snapshot SID -o FILEТо же что screenshot плюс непрочитанные сообщения чата от провайдера.
switch-tab SIDПереключить активную вкладку.
upload SID --selector CSS --file PATH [--filename NAME]Приложить файл к input[type=file] по CSS-селектору.

Чат с провайдером

КомандаЧто делает
chat SID send TEXTОтправить текст провайдеру.
chat SID next [--timeout SEC]Заблокироваться до следующего сообщения провайдера или таймаута.
chat SID history [--since TS] [--limit N]Получить историю чата (Unix-ts или ISO-8601 --since).
chat SID send-image --image PATH [--text MSG]Отправить картинку (с опциональным текстом) провайдеру.

Расширенные

КомандаЧто делает
profile SID export -o FILE [--domains CSV] [--no-session-storage]Экспорт cookies / localStorage / sessionStorage в JSON. Фильтр --domains a.com,b.com.
profile SID import -i FILEИмпорт ранее экспортированного профиля в сессию.
request-captcha SID [--acceptance SEC] [--completion SEC] [--manual]Попросить провайдера решить капчу. --manual отключает auto-accept, агент голосует явно.
configure SID [--masking-mode VAL] [--fingerprint VAL]Поменять masking / fingerprint в рантайме.
cdp SID --method METHOD [--params JSON]Отправить сырую Chrome DevTools Protocol команду. Escape-hatch для всего, что не покрыто high-level API.

Вывод и ошибки

Успешные команды пишут одну JSON-строку в stdout. Ошибки идут в stderr как JSON с полями "error" и "code". Прогоняй stdout через jq для цепочки команд в скриптах.

Коды выхода

КодЗначение
0успех
1общая ошибка
2CEKI_API_KEY не задан
3сессия не найдена или ты не владелец
4таймаут (приём капчи, ожидание чата и т.д.)
5сетевая ошибка / разрыв соединения
130прерывание (Ctrl-C)

REST API

Прямые HTTP-запросы для полного контроля:

Аренда сессии

HTTP
POST /api/sessions/rent
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "geo": "DE",
  "duration": 300,
  "budget": 0.50
}

Ответ

JSON
{
  "session_id": "sess_abc123",
  "ws_url": "wss://browser.ceki.me/ws/sess_abc123",
  "host_geo": "DE",
  "rate_per_min": 0.05,
  "expires_at": "2026-04-30T15:05:00Z"
}

Эндпоинты

МетодЭндпоинтОписание
POST/api/sessions/rentАренда браузерной сессии
POST/api/sessions/{id}/navigateНавигация по URL
POST/api/sessions/{id}/clickКлик по селектору
POST/api/sessions/{id}/fillЗаполнение формы
POST/api/sessions/{id}/extractИзвлечение данных
POST/api/sessions/{id}/screenshotСкриншот
DELETE/api/sessions/{id}Завершение сессии
GET/api/geolocationsДоступные геолокации
WS/ws/{session_id}Управление в реальном времени

Протокол MCP

Ceki нативно поддерживает Model Context Protocol — открытый стандарт подключения AI-агентов к внешним инструментам. Работает с Claude, GPT, LangChain и любым MCP-совместимым агентом.

Конфигурация

Конфигурация та же, что в разделе «Быстрый старт»:

JSON
{
  "mcpServers": {
    "ceki": {
      "url": "https://api.ceki.me/mcp/agent",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Доступные инструменты

ИнструментОписание
rent_browserАренда реальной браузерной сессии в указанной геолокации
navigateНавигация браузера по URL
clickКлик по элементу через CSS-селектор
fillЗаполнение полей формы
extractИзвлечение текста/данных со страницы по селекторам
screenshotСкриншот текущей страницы
closeЗакрытие сессии и освобождение ресурсов

Пример диалога с агентом

Dialog
User: "Rent a browser in Germany and check the price on example.com"

Agent: [calls rent_browser(geo="DE", duration=60)]
  -> Session sess_abc123 ready

Agent: [calls navigate(url="https://example.com")]
  -> Page loaded, title: "Example Domain"

Agent: [calls extract(selector=".price")]
  -> Extracted: "$29.99"

Agent: [calls close()]
  -> Session ended

Agent: "The price on example.com is $29.99 (checked from a German IP)."

Аутентификация

Все API-запросы требуют Bearer-токен в заголовке Authorization.

HTTP Header
Authorization: Bearer YOUR_API_KEY

Получение API-ключа

Вариант 1 (MCP): Вызовите публичный MCP-tool register-agent — полный флоу описан в Быстром старте выше.

Вариант 2 (Dashboard): Зарегистрируйтесь на ceki.me, затем перейдите в Dashboard → Agents → Create Agent. api_key показывается один раз — скопируйте сразу.

Безопасность: Никогда не раскрывайте API-ключ в клиентском коде. Используйте переменные окружения или менеджер секретов.

Вебхуки

Получайте уведомления о событиях сессий в реальном времени через HTTP-вебхуки.

События

СобытиеОписание
session.startedСессия запущена и готова к работе
session.endedСессия завершена или истекло время
session.errorПроизошла ошибка при выполнении сессии

Пример payload

JSON
{
  "event": "session.ended",
  "session_id": "sess_abc123",
  "timestamp": "2026-04-30T15:05:00Z",
  "data": {
    "duration_seconds": 47,
    "total_cost": 0.24,
    "host_geo": "DE",
    "pages_visited": 3
  }
}
Настройте вебхуки в Панель управления → Настройки → Вебхуки. На каждый URL отправляется POST-запрос с JSON-payload.