API de cloud phone Android: REST e ADB

Q: Posso criar aparelhos pela API?

Sim. GET /v1/models lista o que você pode criar; POST /v1/devices com um modelo, uma rede e um plano cria um aparelho. Envie um cabeçalho Idempotency-Key para que uma nova tentativa depois de um timeout nunca crie nem cobre duas vezes.

Q: Como os agentes de IA usam a API?

GET /v1/devices/{name}/observe devolve uma captura de tela atual e os elementos da tela com suas posições; POST /v1/devices/{name}/act toca, digita ou desliza e espera a tela estabilizar. API observe e act para agentes de IA

A API do Clousd é uma API REST em https://api.clousd.com/v1 para celulares Android na nuvem, não para linhas telefônicas. Toda ação do painel é uma chamada que você mesmo pode fazer: criar aparelhos, trocar a rede, instalar apps, fazer snapshots e clonar. Tudo é uma chamada: tarefas longas respondem 202, as chaves têm escopo, os webhooks são assinados e o ADB está a um comando de distância.

Gere sua chave de API Referência da API

RESTJSON sobre HTTPS 202+ tarefa para operações longas webhooks

GET /v1/devices

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

200 OKResposta

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

Chaves fáceis de entender.

Crie uma chave em Configurações → Chaves de API. Cada chave tem um escopo e uma lista de aparelhos que pode acessar, e ela aparece uma única vez. Revogue por lá quando precisar.

leitura ou controleUma chave de leitura só olha, não muda nada; uma chave de controle pode agir.
Limitada a aparelhosUma chave só vê os aparelhos da sua lista e os novos aparelhos que ela mesma cria ou clona.
Limites de requisições por chave60 requisições por minuto, e até 120 por minuto por aparelho nas rotas de aparelho.

URL base e autenticação

# em toda requisição
https://api.clousd.com/v1
Authorization: Bearer cl_live_your_key

# operações longas respondem 202 com uma tarefa
POST /v1/devices/c3f9a41d2/restart
→ 202 { "job": { "id": "3f9c…", "kind": "restart", "state": "running" } }
GET  /v1/jobs/3f9c…
→ 200 { "job": { "state": "done" } }

As chamadas que você vai usar.

São as primeiras da maioria dos scripts; todas as rotas da API v1, com todos os campos, estão na referência. Chegou agora? Comece pelo início rápido em cinco passos.

Aparelhos

ciclo de vida

GET/v1/modelsO que dá para criar

POST/v1/devicesCrie um aparelho

GET/v1/devicesListar aparelhos

POST/v1/devices/{name}/startLigar · parar · reiniciar

DELETE/v1/devices/{name}Excluir de vez

Tela e entrada

controle

GET/v1/devices/{name}/screenshotPNG, ou um JPEG leve

POST/v1/devices/{name}/actionAbrir app, tocar, digitar, achar texto

POST/v1/devices/{name}/inputToques e teclas brutos

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

Rede

saídas

GET/v1/network/optionsTipos e países à venda

POST/v1/devices/{name}/networkTrocar a saída

POST/v1/devices/{name}/network/rotateNovo endereço

POST/v1/network/checkTestar seu próprio proxy

Apps

como da Play Store

GET/v1/appsCatálogo

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

GET/v1/devices/{name}/appsO que está instalado

POST/v1/devices/{name}/apkEnviar seu APK

Snapshots

estado

POST/v1/devices/{name}/snapshotsSalvar um estado

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

POST/v1/devices/{name}/snapshots/{id}/cloneNovo aparelho a partir dele

Frota

vários aparelhos

POST/v1/groupsRodar passos em vários aparelhos

GET/v1/schedulesAgendas semanais

GET/v1/healthSaúde dos seus aparelhos

GET/v1/usageMinutos por aparelho

Por tarefa: snapshots e clones, trocar a rede de um celular, rodar testes a partir do CI.

ADB, sem porta aberta.

Nenhum aparelho expõe o ADB para a internet. Você se conecta ao nosso relay, entra com um código único, e o relay leva sua sessão até aquele aparelho e a nenhum outro. Ele fica desligado até você ligar.

Só os seus IPsPara ligar, é obrigatória uma lista de até 20 endereços ou faixas.
Com prazo24 horas por padrão, até 7 dias; depois ele se desliga sozinho.
Tudo funcionainstall, shell, logcat, push e pull. Comandos perigosos, como root ou reboot, são recusados.

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

Proteção	O que acontece	Limite
Endereços permitidos	Conexões de qualquer outro lugar são fechadas na hora	até 20 IPs ou faixas
Expiração	O relay do aparelho se desliga e o código é apagado	24 h por padrão, 7 dias no máximo
Sessões	A quarta conexão é recusada	3 simultâneas por aparelho
Códigos errados	A sessão é fechada; depois de 20, o relay do aparelho se desliga	5 por sessão · 20 a cada 10 min
Sessão ociosa	Fechada; shell e logcat ao vivo não contam como ociosidade	30 minutos
Push e pull	Novas transferências de arquivos nessa sessão são recusadas	2 GiB por sessão
Sempre recusados	Também disable-verity, reverse, tcpip, usb, jdwp, sideload, restore	root, remount, reboot, …

Webhooks assinados.

Defina uma URL de webhook numa chave, e a plataforma envia um POST para ela quando algo acontece nos aparelhos dessa chave: uma tarefa termina, um aparelho apresenta um problema, o problema se resolve.

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

EVENThealth.problemum aparelho precisa de atenção

EVENThealth.resolvedestá tudo bem de novo

Três tentativas de entrega: na hora, depois de 10 segundos e depois de um minuto. Cada requisição leva X-Clousd-Signature.

Verifique a assinatura · Python

import hashlib, hmac

# o segredo HMAC é o hash SHA-256 em hex da sua chave 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": {…}}

Erros que você consegue tratar.

Códigos de status HTTP padrão e um corpo JSON com um kind legível por máquina e uma mensagem para pessoas: {"error": "busy", "message": "…"}

Status	O que significa	Kind
400	Um campo está faltando ou não é um dos valores permitidos	bad_request
401	Chave ausente, errada ou revogada	unauthorized
402	Saldo insuficiente para o que você pediu	insufficient_funds
403	O escopo ou a lista de aparelhos da chave não permite	forbidden
404	Nenhum aparelho, tarefa ou snapshot com esse nome para esta chave	not_found
409	O aparelho já está nesse estado ou ocupado com outra tarefa	busy
429	Requisições demais: espere um pouco e tente de novo	rate_limited

Dúvidas sobre a API de cloud phone

Ficou alguma dúvida? Escreva para o suporte e uma pessoa responde, normalmente em até um dia útil.

A API custa à parte?

Não. A API, os webhooks e o ADB estão incluídos. Você paga pelos aparelhos enquanto estão ligados: $0.004 por minuto ou $12.00 por mês. Sem planos por nível, API em todas as contas

Posso criar aparelhos pela API?

Sim. GET /v1/models lista o que você pode criar; POST /v1/devices com um modelo, uma rede e um plano cria um aparelho. Envie um cabeçalho Idempotency-Key para que uma nova tentativa depois de um timeout nunca crie nem cobre duas vezes.

Tem SDK?

A API é REST pura e funciona em qualquer linguagem com um cliente HTTP. Um SDK em Python e um servidor MCP para agentes de IA chegam junto com o acesso antecipado para agentes.

Como os agentes de IA usam a API?

GET /v1/devices/{name}/observe devolve uma captura de tela atual e os elementos da tela com suas posições; POST /v1/devices/{name}/act toca, digita ou desliza e espera a tela estabilizar. API observe e act para agentes de IA

Posso usar ADB pela internet?

Sim, pelo nosso relay: ative o ADB num aparelho, libere seus endereços IP, conecte com adb connect e entre com um código único. Ele vem desligado e se desliga sozinho depois de 24 horas, ou de até 7 dias, se você preferir.

Onde fica a referência completa?

Em /docs/reference/, gerada a partir da descrição OpenAPI, que você também pode baixar como openapi-v1.yaml.

Onde vejo se a API está no ar?

Na página de status da API: verificações reais da API e do gateway por trás das telas ao vivo e do ADB, feitas no máximo a cada cinco minutos, com 90 dias de histórico diário.

Teste grátis

Gere uma chave. Programe seu primeiro aparelho em um minuto.

Sem cartão, sem recarga.
Crie uma conta, inicie um aparelho e use por meia hora.
Se resolver, adicione saldo e siga em frente. Se não, você não perdeu nada.

Crie uma conta Ler a documentação

Celular parado não custa nadaUm teste por conta, e o aparelho guarda o estado