Перейти к основному содержимому

Cloud Phones API

Используйте обычный API-ключ, чтобы создавать профили в оплаченных слотах, запускать телефоны, открывать приватный просмотр и управлять root и ADB (Android Debug Bridge — соединение для управления Android). Биллинг, проверка владельца и ограничения устройства такие же, как в кабинете.

Swagger: cloud-phones содержит действующую схему. Со страницы «Доступ к API» откройте Swagger или API Docs. В Swagger нажмите Authorize → ApiKeyAuth и вставьте ключ; запросы используют заголовок X-Api-Key.

Предварительные условия​

Нужны активный аккаунт, ключ из раздела API Keys, свободный оплаченный слот профиля, действующий оплаченный период, положительный баланс минут и доступная прокси. Создание резервирует существующий слот: не покупает слоты и не запускает телефон. Работа запущенного телефона расходует оплаченные минуты. Root зависит от поддержки устройства провайдером; включение ADB доступно для Android 11–15.

export BASE_URL='https://app.cyberyozh.com'
export API_KEY='replace-with-your-api-key'

Не передавайте API-ключ в URL. Каждый API-запрос ниже требует X-Api-Key; открытие телефона в браузере использует обычный вход в аккаунт. API-ключ, пароль прокси и пароль ADB — приватные данные.

МетодПуть после /api/v2/cloud-phones/profiles/Назначение
GET(коллекция)Список своих профилей
POST(коллекция)Создание в свободном оплаченном слоте
GET{id}/Профиль и результат запуска
POST{id}/start/Запрос запуска
POST{id}/adb/Включение/выключение ADB
GET{id}/adb/Реквизиты подключения ADB
POST{id}/root/Включение/выключение root

Публичный API содержит семь операций. Покупка слотов, остановка, удаление, клонирование, приложения и GPS через него не предоставляются.

1. Список своих профилей​

curl "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}"

Пример HTTP 200 при отсутствии профилей:

{"count":0,"next":null,"previous":null,"currentPage":1,"nextPage":null,"prevPage":null,"results":[]}

Список разбит на страницы: count, next, previous, currentPage, nextPage, prevPage, results. Параметры запроса: page, page_size, search, status, group (UUID своей группы). Например, ?status=running&page_size=10. Возвращаются только свои неудалённые профили. Без ключа, с неверным, отозванным или истёкшим ключом — 403, даже при наличии браузерной сессии. Запрос чужого профиля возвращает 404 без данных и ссылки.

2. Создание профиля​

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"name":"Automation phone","proxy":{"proxy_information":"socks5://example-user:example-password@203.0.113.10:1080"},"device":{"android_version":"13","region":"sgp"}}'

Замените учебную прокси своей действующей. Поле name обязательно; note, настройки устройства и прокси необязательны. Профиль можно сохранить без прокси, но запустить получится только после её настройки. Регион устройства — cn, sgp или us; для us нужен Android 15. Android по умолчанию — 13. Полный набор полей создания и режимов прокси смотрите в Swagger.

Пример HTTP 201:

{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Automation phone",
"note": "",
"status": "slot_reserved",
"is_viewable": false,
"view_url": null,
"runtime": {
"elapsed_seconds": null,
"confirmed_seconds": 0,
"current_started_at": null,
"as_of": null,
"accuracy": "unknown",
"reason": "legacy_history"
},
"android_version": "13",
"device_model": null,
"proxy_source": "manual",
"proxy": {
"source": "manual",
"configured": true,
"is_expired": false,
"scheme": "socks5",
"host": "203.0.113.10",
"port": 1080,
"user_proxy_ref": null,
"rotating_sub_user_id": null,
"rotating": null,
"manual_information": "socks5://example-user:example-password@203.0.113.10:1080"
},
"groups": [],
"is_root_enabled": false,
"is_adb_enabled": false,
"created_at": "2026-11-10T05:00:00Z",
"last_started_at": null,
"last_start_error": null
}

Сохраните настоящий id из своего ответа:

export PROFILE_ID='replace-with-created-profile-id'

slot_reserved означает: слот занят профилем, телефон ещё не создан у провайдера и не запущен. Если свободного слота нет — 402 с code: "no_free_slots". Запланированное уменьшение лимита слотов может вернуть 409 с code: "profiles_pending_limit".

3. Запуск и проверка результата​

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/start/" \
-H "X-Api-Key: ${API_KEY}"

Тело запроса отсутствует. HTTP 200 возвращает полный профиль, обычно с status: "starting" и view_url: null. Запуск асинхронный; повторный start во время запуска или работы не отправляет второй запуск.

Опрашивайте детали с задержкой между запросами и общим ограничением времени ожидания:

curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/" \
-H "X-Api-Key: ${API_KEY}"

HTTP 200 возвращает полный профиль. Ждите непустой view_url; прекращайте ожидание при непустом last_start_error. Выдержка из готового профиля:

{
"id": "11111111-1111-4111-8111-111111111111",
"status": "running",
"is_viewable": true,
"view_url": "https://app.cyberyozh.com/my-account/cloud-phones/view/11111111-1111-4111-8111-111111111111/",
"last_start_error": null
}

Ошибка запуска видна в профиле, даже если первоначальный start вернул 200. Пример полей:

{
"status": "stopped",
"view_url": null,
"last_start_error": {
"code": "provider_start_failed",
"detail": "The phone did not start: the cloud phone service refused to start it. Try again later.",
"failed_at": "2026-11-10T05:01:00Z"
}
}

4. Открытие телефона​

Откройте полученный view_url в браузере. Это owner-link карточки телефона на основном домене приложения из настроек и с английским маршрутом по умолчанию, независимо от Accept-Language. Ссылка не содержит API-ключа и bearer-токена просмотра. Гость проходит обычный вход и возвращается к запрошенному телефону; другой аккаунт не может получить профиль или сеанс просмотра.

У одного готового профиля ссылка одинакова в списке и деталях. view_url — URI только для чтения, допускающий null: для зарезервированного, остановленного, запускающегося или ошибочного телефона и при отсутствии действительного сеанса текущего запуска значение null. Одного running недостаточно. После перезапуска надо снова дождаться готовности. Существующее is_viewable может быть true уже во время starting; готовность открытия через публичный API определяйте по view_url.

Это не гостевая ссылка. Сохранённый URL не поддерживает телефон во включённом состоянии и не обходит повторные проверки доступа и состояния.

5. Включение ADB и реквизиты подключения​

Телефон должен работать. Включение ADB поддерживает Android 11–15; неподдерживаемая версия возвращает 422. Флаг меняется после подтверждения провайдера.

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'

HTTP 200 возвращает полный профиль с is_adb_enabled: true. Это ещё не готовность соединения. Опрашивайте с задержкой и ограничением времени:

curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}"

Пример HTTP 200 (все четыре значения — строки):

{
"ip": "203.0.113.20",
"port": "5555",
"password": "example-adb-password",
"connect_command": "adb connect 203.0.113.20:5555"
}

Используйте возвращённый connect_command и пароль соединения, когда он запрашивается. 409 означает подготовку ADB либо остановленный телефон: сначала проверьте профиль. 422 — ADB выключен или недоступен на устройстве; одно ожидание не поможет. Для выключения отправьте POST {"enabled":false}. GET и HEAD не переключают флаг ADB.

6. Включение root​

Root — расширенные права Android. Нужны работающий телефон и поддержка root провайдером на этом устройстве.

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/root/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'

HTTP 200 возвращает полный профиль с is_root_enabled: true, сохранённым после подтверждения провайдера. Последующий GET профиля показывает оба включённых флага, если обе операции прошли успешно. Остановленный телефон возвращает 409; отказ провайдера — 502 без изменения флага. Для выключения root отправьте POST {"enabled":false}.

Ошибки и лимиты​

HTTPЗначение / действие
400Неверное поле, настройки устройства/прокси или истёкшая прокси
402Нет свободного оплаченного слота, период истёк или нет минут
403Ключ отсутствует, неверен, отозван или истёк
404Профиль отсутствует, удалён, чужой или UUID неверен
405Метод не предоставляется по этому пути
409Конфликт состояния, подготовка ADB или будущий лимит слотов
422ADB выключен/недоступен или устройство не поддерживает действие
429Лимит запросов; учитывайте Retry-After
502/503Отказ или временная недоступность провайдера

Доменные ошибки содержат detail и иногда code, например:

{"detail":"No free profile slots.","code":"no_free_slots"}

Другие коды платного доступа: period_expired, no_minutes. Валидация может вернуть сообщения по именам полей:

{"name":["This field is required."]}

Не рассчитывайте на detail/code в каждой ошибке: используйте HTTP-статус и код при его наличии. Сообщения могут переводиться.

Список/детали/создание: 50 запросов в секунду на пользователя; запуск: 20; root и ADB: 5. Бюджет общий с соответствующими операциями кабинета и остальными ключами того же пользователя. Ограничивайте повторные запросы и время ожидания; учитывайте Retry-After.