Документация API Ceki.me
Арендуйте реальные браузерные сессии через MCP, Python SDK, JavaScript SDK или REST API
Быстрый старт
Два способа начать работу с Ceki — выберите подходящий.
Путь A — Саморегистрация агента через MCP
Позвольте вашему AI-агенту зарегистрироваться самостоятельно без ручной настройки.
1. Добавьте MCP-конфиг (без авторизации)
{
"mcpServers": {
"ceki": {
"url": "https://api.ceki.me/mcp/agent"
}
}
}2. Попросите агента зарегистрироваться
"Зарегистрируй меня как Ceki-агента. Имя: my-agent. Email: you@example.com"3. Агент вызывает register-agent
Бэкенд возвращает api_key в ответе и отправляет 6-значный код подтверждения на указанный email.
4. Подтвердите email
"Подтверди мой email кодом 123456"5. Переподключите MCP с авторизацией
{
"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
Зарегистрируйтесь через веб-интерфейс и создайте ключ агента.
- Зарегистрируйтесь на ceki.me (email + пароль + OTP)
- Откройте Dashboard → Agents
- Нажмите Create Agent, заполните форму, скопируйте
api_keyиз диалога (показывается один раз) - Добавьте ключ в MCP-конфиг (Authorization: Bearer ag_...)
- Переведите крипту на адрес кошелька в Dashboard — статус станет active
{
"mcpServers": {
"ceki": {
"url": "https://api.ceki.me/mcp/agent",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Python SDK
Установите SDK и арендуйте сессию в несколько строк:
pip install ceki-sdkimport 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+ и современными браузерами.
npm install @ceki/sdkimport { 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:
pip install ceki-sdkNode.js:
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). |
Быстрый старт
Пять команд: арендовать, управлять, закрыть:
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 $SIDCLI сохраняет состояние сессии локально — после 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 | общая ошибка |
2 | CEKI_API_KEY не задан |
3 | сессия не найдена или ты не владелец |
4 | таймаут (приём капчи, ожидание чата и т.д.) |
5 | сетевая ошибка / разрыв соединения |
130 | прерывание (Ctrl-C) |
REST API
Прямые HTTP-запросы для полного контроля:
Аренда сессии
POST /api/sessions/rent
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"geo": "DE",
"duration": 300,
"budget": 0.50
}Ответ
{
"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-совместимым агентом.
Конфигурация
Конфигурация та же, что в разделе «Быстрый старт»:
{
"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 | Закрытие сессии и освобождение ресурсов |
Пример диалога с агентом
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.
Authorization: Bearer YOUR_API_KEYПолучение API-ключа
Вариант 1 (MCP): Вызовите публичный MCP-tool register-agent — полный флоу описан в Быстром старте выше.
Вариант 2 (Dashboard): Зарегистрируйтесь на ceki.me, затем перейдите в Dashboard → Agents → Create Agent. api_key показывается один раз — скопируйте сразу.
Вебхуки
Получайте уведомления о событиях сессий в реальном времени через HTTP-вебхуки.
События
| Событие | Описание |
|---|---|
session.started | Сессия запущена и готова к работе |
session.ended | Сессия завершена или истекло время |
session.error | Произошла ошибка при выполнении сессии |
Пример payload
{
"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
}
}