ADB remoto por internet y primeros pasos con la API.

Guía rápida

Cinco pasos desde una cuenta nueva hasta un dispositivo que controlas con un script. Todo esto también se puede hacer a mano en el panel.

1. Crea una cuenta

   Regístrate con tu correo, Google o GitHub. Tu primer dispositivo funciona 30 minutos gratis, sin tarjeta y sin recarga.

2. Recarga saldo

   Facturación → Recargar saldo, desde $10 con cripto, WeChat Pay o Alipay. Los dispositivos se cobran de este saldo prepago; si no queda saldo, una llamada de creación responde 402.

3. Crea una clave de API

   Ajustes → Claves de API. Elige el permiso, read o control, y los dispositivos que cubre. La clave se muestra una sola vez.

4. Crea un dispositivo

   Lista los modelos que puedes crear y luego crea uno con una red y un plan.

5. Míralo arrancar

   El dispositivo aparece como starting y pasa a running en cerca de un minuto, con el país y la dirección de su salida.

export CLOUSD_KEY=cl_live_your_key

# 1. ¿qué puedo crear? - ids de modelo con su versión de Android
curl https://api.clousd.com/v1/models -H "Authorization: Bearer $CLOUSD_KEY"

# 2. crear: Galaxy A16 5G con Android 15, salida móvil en EE. UU., cobro por minuto
curl -X POST https://api.clousd.com/v1/devices \
  -H "Authorization: Bearer $CLOUSD_KEY" \
  -H "Idempotency-Key: first-device-001" \
  -d '{"profile":"galaxya16","plan":"metered","network":{"type":"mobile","country":"US"}}'
# → 202 {"ok": true, "name": "c3f9a41d2", "state": "starting", "poll": "/v1/devices/c3f9a41d2"}

# 3. consultar hasta que esté encendido
curl https://api.clousd.com/v1/devices/c3f9a41d2 -H "Authorization: Bearer $CLOUSD_KEY"

Dispositivos

Un dispositivo es un teléfono de un modelo con una versión de Android. Conserva sus apps y datos entre paradas y reinicios hasta que lo eliminas.

Iniciar, detener y reiniciar responden 202 con una tarea. Eliminar es definitivo: borra el dispositivo y sus datos, y no se puede deshacer. Los planes son por dispositivo: metered ($0.004 por minuto, como máximo $0.80 al día) o monthly ($12.00 por 30 días).

POST   /v1/devices/{name}/start
POST   /v1/devices/{name}/stop
POST   /v1/devices/{name}/restart
GET    /v1/devices/{name}/screenshot?w=320     # PNG, o un JPEG pequeño con w
POST   /v1/devices/{name}/action  {"op":"open_app","package":"com.android.chrome"}
DELETE /v1/devices/{name}                     # definitivamente

action ejecuta un paso sin transmisión en vivo: open_app, close_app, url, tap, swipe, text, key, scroll, y las ayudas de texto find_text, tap_text, wait_text, screen_text.

Red

Cada dispositivo tiene una salida. GET /v1/network/options lista los tipos y países que puedes elegir ahora mismo.

POST /v1/devices/{name}/network         {"type":"residential","country":"GB"}
POST /v1/devices/{name}/network         {"url":"socks5://user:pass@203.0.113.7:1080"}
POST /v1/devices/{name}/network/rotate  # dirección nueva, mismo tipo y país
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

La zona horaria, el idioma, la SIM y la ubicación informada siguen a la salida. La salida se aplica por debajo de Android, el DNS pasa por ella y el tráfico se corta si se cae. Cómo funciona

Apps

Instala desde nuestro catálogo como un teléfono instala desde Play Store, o sube cualquier APK.

GET  /v1/apps                                # paquete, título, categoría, versión, tamaño
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # qué está instalado desde el catálogo
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

Las instalaciones del catálogo informan Play Store como instalador. Si ya está instalada la misma versión o una más nueva, la tarea termina con “already”.

Snapshots y clones

Un snapshot congela el dispositivo: apps, sesiones, archivos y ajustes. Restáuralo para volver atrás; clónalo para crear dispositivos nuevos con la misma configuración y su propio número de serie, IMEI, SIM y Android ID.

POST /v1/devices/{name}/snapshots                  {"name":"ready-v3"}
GET  /v1/devices/{name}/snapshots
POST /v1/devices/{name}/snapshots/{id}/restore
POST /v1/devices/{name}/snapshots/{id}/clone    {"name":"eu01"}

Los clones son dispositivos normales, se cobran como cualquier otro y se suman a la lista de la clave que los creó. Para copias con horario usa Panel → Snapshots → Copia nocturna.

Grupos y horarios

Una tarea de grupo ejecuta una lista de pasos en muchos dispositivos, y cada dispositivo empieza en un momento aleatorio dentro del desfase que indiques. El avance se informa por dispositivo en la tarea.

POST /v1/groups
{
  "phones":  ["c3f9a41d2", "c81d07e5a", "c2b9f4a10"],
  "stagger": [30, 180],
  "steps": [
    {"op":"install_app","package":"com.instagram.android"},
    {"op":"open_app","package":"com.instagram.android"},
    {"op":"browse","seconds":240},
    {"op":"wait","seconds":20,"seconds_max":90},
    {"op":"screenshot"}
  ]
}

Pasos: open_app, close_app, install_app, url, tap, swipe, text, key, wait (aleatorio entre seconds y seconds_max), browse (desplazamientos y pausas aleatorios, 10–600 s), scroll, if_text / unless_text (salta los pasos siguientes salvo que haya un texto en pantalla), screenshot, start, stop, restart.

Un horario es la misma tarea con reloj: POST /v1/schedules con name, phones, steps, stagger, at ("HH:MM", UTC) y days (1–7). Paúsalo con /toggle y quítalo con /delete. En el panel, Automatización suma flujos armados con bloques y acciones listas para las apps populares. Qué se automatiza en cada app

Acceso ADB

ADB está apagado por defecto. Enciéndelo en un dispositivo indicando las direcciones desde las que te vas a conectar; recibes un host, un puerto y un código de acceso de un solo uso, que se muestra una sola vez.

POST /v1/devices/{name}/adb  {"ttl_hours":24,"allow_ips":["203.0.113.7","198.51.100.0/24"]}
# → {"host": "…", "port": 27001, "code": "a1b2c3", "expires": "…",
#    "connect": "adb connect host:27001", "login": "adb -s host:27001 shell clousd-login a1b2c3"}

adb connect host:27001
adb -s host:27001 shell clousd-login a1b2c3      # → login ok
adb -s host:27001 install app.apk

DELETE /v1/devices/{name}/adb                 # apagar y cerrar las sesiones

Límites: allow_ips es obligatorio (hasta 20 IP o rangos); ttl_hours vale 24 por defecto y como máximo 168; hasta 3 sesiones por dispositivo; 5 códigos erróneos cierran una sesión y 20 en 10 minutos apagan el relé; las sesiones inactivas se cierran a los 30 minutos; push y pull tienen un límite de 2 GiB por sesión. Root, remount, disable-verity, reverse, reboot, tcpip, usb, jdwp, sideload y restore se rechazan siempre. Emitir un código nuevo cierra las sesiones activas.

Webhooks

Una clave puede tener una URL de webhook (se define al crear la clave). Los eventos de los dispositivos de la clave llegan como un POST con un cuerpo JSON {"event", "ts", "phone", "job" | "incident"}.

Cada solicitud lleva X-Clousd-Signature: el HMAC-SHA256 en hexadecimal del cuerpo sin procesar, con el SHA-256 en hexadecimal de tu clave de API como clave. La entrega se intenta tres veces: al instante, a los 10 segundos y a los 60 segundos, con un tiempo de espera de 10 segundos.

Agentes de IA

Dos llamadas le dan a un agente su ciclo: mirar y luego actuar.

GET /v1/devices/{name}/observe?w=540
# → {"seq": 41, "image": {"w": 540, "format": "jpeg", "data": "…"}, "package": "…", "activity": "…",
#    "ui": [{"text": "Checkout", "id": "…", "b": [60, 1560, 1020, 1680], "click": true}, …]}

POST /v1/devices/{name}/act  {"op":"tap_text","text":"Checkout","seq":41,"settle":true}
# → {"ok": true, "seq": 42, "settled": true, "waited_ms": 830}

observe siempre toma una captura nueva y devuelve hasta 500 elementos de la pantalla con sus límites. act se rechaza con 409 stale si hubo otro observe o act después del seq que envías, así un agente nunca actúa sobre una imagen vieja; con settle espera a que la pantalla deje de cambiar (hasta 5 s). Entre ejecuciones, reinicia restaurando un snapshot. Teléfonos para agentes de IA

Errores y límites

Los errores son JSON con un tipo legible por máquina y un mensaje: {"error": "busy", "message": "…"}. Códigos de estado: 400 solicitud incorrecta, 401 sin autorización, 402 saldo insuficiente, 403 prohibido por el permiso o la lista de dispositivos, 404 no encontrado, 409 ocupado o desactualizado, 429 límite de solicitudes.

Límites por clave: 60 solicitudes por minuto; en las rutas /devices/{name}/…, 120 por minuto por dispositivo y 600 por minuto en total entre dispositivos. Un 429 significa que debes bajar el ritmo y reintentar con espera progresiva.

Equipo y claves de API

Una cuenta tiene dueños y operadores. Los dueños se encargan de la facturación, las claves de API, el equipo y la creación o eliminación de dispositivos. Los operadores manejan los dispositivos que les asignas: iniciar, detener, apps, red, snapshots y ADB, pero no facturación, claves ni eliminación. Invita personas por correo desde Equipo; se unen al iniciar sesión por primera vez.

Las claves de API pertenecen a la cuenta, no a una persona: cada clave tiene un permiso (read o control) y una lista de dispositivos. Una clave de lectura que llama a una ruta que modifica algo recibe 403. Revocar una clave la desactiva al instante.

Facturación

Clousd funciona con saldo prepago. Recarga desde $10 con cripto, WeChat Pay o Alipay; cada recarga y cada cargo son una línea en Facturación, y Uso muestra los minutos y el costo por dispositivo. Los dispositivos por minuto descuentan $0.004 por minuto mientras están encendidos, nunca más de $0.80 al día; los mensuales descuentan $12.00 una vez cada 30 días. Android 15 suma un 10 %; Android 16, un 25 %, y Android 17, un 25 %. Las salidas a internet de pago se cobran por gigabyte. Cuando el saldo llega a cero, los dispositivos por minuto encendidos se detienen y conservan sus datos. Precios

Cómo obtener ayuda

Escribe a support@clousd.com o usa el formulario de contacto; te responde una persona, normalmente en un día hábil. Incluye el ID del dispositivo que ves en el panel (empieza por dev_) o su nombre en la API, y qué esperabas que pasara. El estado actual de la plataforma está en la página de estado, y los cambios recientes, en las notas de versión.

Glosario

Los términos que usan el panel, la API y esta documentación, en un solo lugar.

Salida

El proxy que se aplica a un dispositivo por debajo de Android: móvil, residencial, ISP, de centro de datos o tu propio proxy SOCKS5 o HTTP. Las apps ven su dirección, y la zona horaria, el idioma y la SIM siguen a su país.

Región

Dónde funciona un dispositivo. Elige la más cercana a quien mira la pantalla o usa ADB; se elige por separado de la salida.

Snapshot

Una copia guardada de todo el dispositivo: apps, sesiones, archivos y ajustes. Restáurala en un paso o clona dispositivos nuevos a partir de ella.

Clonar

Un dispositivo nuevo creado a partir de un snapshot: las mismas apps, archivos y ajustes, con su propio número de serie, IMEI, SIM, direcciones Wi-Fi y Bluetooth y Android ID.

Identidad

Los identificadores de hardware que informa un dispositivo: número de serie, IMEI, número de teléfono y datos de Wi-Fi. Una identidad nueva los reemplaza con una sola llamada.

Receta

Una automatización lista para una acción de una app, como iniciar sesión, calentar, publicar un post o borrar el último post, que se ejecuta en un teléfono, un grupo o con un horario.

Pasos genéricos

Bloques que funcionan en cualquier app: abrir una app o una URL, tocar, deslizar, escribir texto, pulsar una tecla, navegar, desplazarse, esperar, revisar el texto en pantalla y tomar una captura.

Flujo

Una cadena de pasos armada con bloques en Automatización, como iniciar sesión, calentar, pausa y publicar, cada uno con su duración y un margen ±.

Grupo

Un conjunto de dispositivos sobre los que actúas a la vez: iniciar, detener, instalar apps y ejecutar pasos, con un desfase aleatorio entre teléfonos.

Horario

Recetas o pasos que se ejecutan por día de la semana y hora (UTC) en un dispositivo o un grupo.

Recursos

Donde viven las cuentas y los archivos: los datos de acceso de cada cuenta, guardados cifrados y vinculados a un teléfono, y la biblioteca Media.

Biblioteca Media

Carpetas de fotos y videos en Resources. Los pasos de publicación toman el último archivo o uno al azar, y nunca repiten un archivo en el mismo teléfono.

Multi-view y Sync

Un muro de pantallas en vivo, una al lado de la otra. Sync replica un toque, un deslizamiento o un texto en los teléfonos que elijas.

Dueño y operador

Roles del equipo. Los dueños se encargan de la facturación, las claves de API, el equipo y la creación o eliminación de dispositivos; los operadores manejan solo los dispositivos que tienen asignados.

Relé ADB

Cómo llegas a un dispositivo con adb: te conectas al relé y entras con un código de un solo uso. Solo desde tus direcciones IP, apagado por defecto y con caducidad.