Automatización Android: API REST y ADB para teléfonos en la nube.

Q: ¿Puedo crear dispositivos por la API?

Sí. GET /v1/models lista lo que puedes crear; POST /v1/devices con un modelo, una red y un plan crea uno. Envía el encabezado Idempotency-Key para que un reintento tras un timeout nunca cree ni cobre dos veces.

Q: ¿Cómo la usan los agentes de IA?

GET /v1/devices/{name}/observe devuelve una captura reciente y los elementos de la pantalla con sus posiciones; POST /v1/devices/{name}/act toca, escribe o desliza y espera a que la pantalla se estabilice. API observe y act para agentes de IA

La API de Clousd es una API REST en https://api.clousd.com/v1 para teléfonos Android en la nube, no para líneas telefónicas. Cada acción del panel es una llamada que puedes hacer tú: crear dispositivos, cambiar su red, instalar apps, guardar snapshots y clonar. Las tareas largas responden 202, las claves tienen permisos acotados, los webhooks van firmados y ADB está a un comando de distancia.

Obtener clave de API Referencia de la API

RESTJSON sobre HTTPS 202+ tarea para trabajos largos webhooks

GET /v1/devices

curl https://api.clousd.com/v1/devices \
  -H "Authorization: Bearer cl_live_••••••••"

200 OKRespuesta

{ "devices": [
  { "name": "c3f9a41d2", "model": "Galaxy A16 5G",
    "android": "15", "state": "running",
    "exit": { "type": "mobile", "country": "DE",
              "timezone": "Europe/Berlin" },
    "uptime": 7740, "minutes_today": 129 }
] }

Claves fáciles de entender.

Crea una clave en Ajustes → Claves de API. Cada clave tiene un permiso y una lista de dispositivos que puede tocar, y se muestra una sola vez. Revócala desde ahí cuando haga falta.

lectura o controlUna clave de lectura puede mirar, pero no cambiar nada; una clave de control puede actuar.
Limitada a dispositivosUna clave solo ve los dispositivos de su lista y los nuevos que ella misma crea o clona.
Límites por clave60 solicitudes por minuto, y hasta 120 por minuto por dispositivo en las rutas de dispositivos.

URL base y autenticación

# en cada solicitud
https://api.clousd.com/v1
Authorization: Bearer cl_live_your_key

# las operaciones largas responden 202 con un job
POST /v1/devices/c3f9a41d2/restart
→ 202 { "job": { "id": "3f9c…", "kind": "restart", "state": "running" } }
GET  /v1/jobs/3f9c…
→ 200 { "job": { "state": "done" } }

Las llamadas que vas a usar.

Con estas empieza la mayoría de los scripts; todas las rutas de la API v1, con cada campo, están en la referencia. ¿Eres nuevo? Empieza por la guía rápida en cinco pasos.

Dispositivos

ciclo de vida

GET/v1/modelsQué puedes crear

POST/v1/devicesCrea un dispositivo

GET/v1/devicesListar dispositivos

POST/v1/devices/{name}/startIniciar · detener · reiniciar

DELETE/v1/devices/{name}Eliminar para siempre

Pantalla y entrada

control

GET/v1/devices/{name}/screenshotPNG o un JPEG liviano

POST/v1/devices/{name}/actionAbrir app, tocar, escribir, buscar texto

POST/v1/devices/{name}/inputToques y teclas directos

GET/v1/devices/{name}/logsLogcat reciente

Red

salidas

GET/v1/network/optionsTipos y países disponibles

POST/v1/devices/{name}/networkCambiar la salida

POST/v1/devices/{name}/network/rotateNueva dirección

POST/v1/network/checkProbar tu propio proxy

Apps

como desde Play

GET/v1/appsCatálogo

POST/v1/devices/{name}/appsInstalar del catálogo

GET/v1/devices/{name}/appsQué está instalado

POST/v1/devices/{name}/apkSubir tu APK

Snapshots

estado

POST/v1/devices/{name}/snapshotsGuardar un estado

POST/v1/devices/{name}/snapshots/{id}/restoreVolver atrás

POST/v1/devices/{name}/snapshots/{id}/cloneNuevo dispositivo a partir de él

Flota

muchos dispositivos

POST/v1/groupsEjecutar pasos en muchos dispositivos

GET/v1/schedulesHorarios semanales

GET/v1/healthEstado de tus dispositivos

GET/v1/usageMinutos por dispositivo

Por tarea: snapshots y clones, cambiar la red de un teléfono, ejecutar pruebas desde CI.

ADB, sin puertos abiertos.

Ningún dispositivo expone ADB a internet. Te conectas a nuestro relé, entras con un código de un solo uso, y el relé lleva tu sesión a ese dispositivo y a ningún otro. Está apagado hasta que lo enciendes.

Solo tus IPPara encenderlo hace falta una lista de hasta 20 direcciones o rangos permitidos.
Con caducidad24 horas por defecto, hasta 7 días; después se apaga solo.
Todo funcionainstall, shell, logcat, push y pull. Los comandos peligrosos, como root o reboot, se rechazan.

Terminal

# the dashboard or POST /v1/devices/{name}/adb gives host, port and code
adb connect relay.clousd.com:27001
adb -s relay.clousd.com:27001 shell clousd-login a1b2c3
login ok

adb -s relay.clousd.com:27001 install app-release.apk
adb -s relay.clousd.com:27001 logcat -d | tail -40

Protección	Qué pasa	Límite
Direcciones permitidas	Las conexiones desde cualquier otro lugar se cierran al instante	hasta 20 IP o rangos
Caducidad	El relé del dispositivo se apaga y el código se borra	24 h por defecto, 7 días máx.
Sesiones	Una cuarta conexión se rechaza	3 a la vez por dispositivo
Códigos erróneos	La sesión se cierra; tras 20, el relé del dispositivo se apaga	5 por sesión · 20 cada 10 min
Sesión inactiva	Se cierra; un shell o un logcat en curso no cuentan como inactividad	30 minutos
Push y pull	Se rechazan más transferencias de archivos en esa sesión	2 GiB por sesión
Siempre rechazado	También disable-verity, reverse, tcpip, usb, jdwp, sideload, restore	root, remount, reboot, …

Webhooks firmados.

Asígnale a una clave una URL de webhook y la plataforma le enviará un POST cuando pase algo en los dispositivos de esa clave: termina una tarea, un dispositivo tiene un problema, el problema se resuelve.

EVENTjob.finishedstart, stop, network, snapshot, clone…

EVENThealth.problemun dispositivo necesita atención

EVENThealth.resolvedvuelve a estar bien

Tres intentos de entrega: al instante, a los 10 segundos y al minuto. Cada solicitud lleva X-Clousd-Signature.

Verificar la firma · Python

import hashlib, hmac

# el secreto HMAC es el digest SHA-256 en hex de tu clave de API
secret = hashlib.sha256(API_KEY.encode()).hexdigest().encode()
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, headers["X-Clousd-Signature"]):
    raise PermissionError("bad signature")

# body: {"event": "job.finished", "ts": …, "phone": "c3f9a41d2", "job": {…}}

Errores fáciles de manejar.

Códigos de estado HTTP estándar y un cuerpo JSON con un tipo legible por máquina y un mensaje para personas: {"error": "busy", "message": "…"}

Estado	Qué significa	Tipo
400	Falta un campo o no tiene un valor permitido	bad_request
401	Clave ausente, incorrecta o revocada	unauthorized
402	No hay saldo suficiente para lo que pediste	insufficient_funds
403	El permiso o la lista de dispositivos de la clave no lo permiten	forbidden
404	Ese dispositivo, tarea o snapshot no existe para esta clave	not_found
409	El dispositivo ya está en ese estado u ocupado con otra tarea	busy
429	Demasiadas solicitudes: espera y vuelve a intentar	rate_limited

Preguntas sobre la API de teléfonos en la nube

¿Algo más? Escribe a soporte y te responde una persona, normalmente en un día hábil.

¿La API tiene costo adicional?

No. La API, los webhooks y ADB están incluidos. Pagas por los dispositivos mientras están encendidos: $0.004 por minuto o $12.00 al mes. Sin niveles de plan, API en todas las cuentas

¿Puedo crear dispositivos por la API?

Sí. GET /v1/models lista lo que puedes crear; POST /v1/devices con un modelo, una red y un plan crea uno. Envía el encabezado Idempotency-Key para que un reintento tras un timeout nunca cree ni cobre dos veces.

¿Hay un SDK?

La API es REST simple y funciona desde cualquier lenguaje con un cliente HTTP. Un SDK para Python y un servidor MCP para agentes de IA llegan con el acceso anticipado para agentes.

¿Cómo la usan los agentes de IA?

GET /v1/devices/{name}/observe devuelve una captura reciente y los elementos de la pantalla con sus posiciones; POST /v1/devices/{name}/act toca, escribe o desliza y espera a que la pantalla se estabilice. API observe y act para agentes de IA

¿Puedo usar ADB por internet?

Sí, a través de nuestro relé: enciende ADB en un dispositivo, permite tus direcciones IP, conéctate con adb connect y entra con un código de un solo uso. Está apagado por defecto y se apaga solo a las 24 horas, o hasta 7 días si así lo eliges.

¿Dónde está la referencia completa?

En /docs/reference/, generada a partir de la descripción OpenAPI, que también puedes descargar como openapi-v1.yaml.

¿Dónde veo si la API está funcionando?

En la página de estado de la API: comprobaciones reales de la API y del gateway que hay detrás de las pantallas en vivo y de ADB, cada cinco minutos como máximo, con 90 días de historial diario.

Prueba gratis

Obtén una clave. Automatiza tu primer dispositivo en un minuto.

Sin tarjeta y sin recarga.
Crea una cuenta, inicia un dispositivo y úsalo media hora.
Si te sirve, recarga saldo y sigue. Si no, no pierdes nada.

Crea una cuenta Ver la documentación

Un teléfono detenido no cuesta nadaUna prueba por cuenta; el dispositivo conserva su estado