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 или будущий лимит слотов |
| 422 | ADB выключен/недоступен или устройство не поддерживает действие |
| 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.