ADB remoto pela internet e início rápido da API

Início rápido

Cinco passos de uma conta nova até um aparelho que você controla por script. Tudo aqui também pode ser feito à mão, no painel.

1. Crie uma conta

   Cadastre-se com e-mail, Google ou GitHub. Seu primeiro aparelho roda 30 minutos grátis, sem cartão e sem recarga.

2. Adicione saldo

   Cobrança → Adicionar saldo, a partir de $10, com cripto, WeChat Pay ou Alipay. Os aparelhos são cobrados desse saldo pré-pago; sem saldo, uma chamada de criação responde 402.

3. Crie uma chave de API

   Configurações → Chaves de API. Escolha o escopo, read ou control, e os aparelhos que ela cobre. A chave aparece uma única vez.

4. Crie um aparelho

   Liste os modelos que você pode criar e depois crie um, com uma rede e um plano.

5. Acompanhe a inicialização

   O aparelho aparece como starting e passa a running em cerca de um minuto, com o país e o endereço da sua saída de rede.

export CLOUSD_KEY=cl_live_your_key

# 1. o que posso criar? - ids de modelo com a versão do Android
curl https://api.clousd.com/v1/models -H "Authorization: Bearer $CLOUSD_KEY"

# 2. criar: Galaxy A16 5G no Android 15, saída móvel nos EUA, cobrança 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 até o aparelho estar running
curl https://api.clousd.com/v1/devices/c3f9a41d2 -H "Authorization: Bearer $CLOUSD_KEY"

Aparelhos

Um aparelho é um celular de um modelo numa versão do Android. Ele mantém apps e dados entre paradas e reinícios até você excluí-lo.

Ligar, parar e reiniciar respondem 202 com uma tarefa. Excluir é definitivo: remove o aparelho e os dados dele, sem volta. Os planos são por aparelho: metered ($0.004 por minuto, no máximo $0.80 por dia) ou monthly ($12.00 por 30 dias).

POST   /v1/devices/{name}/start
POST   /v1/devices/{name}/stop
POST   /v1/devices/{name}/restart
GET    /v1/devices/{name}/screenshot?w=320     # PNG, ou um JPEG leve com w
POST   /v1/devices/{name}/action  {"op":"open_app","package":"com.android.chrome"}
DELETE /v1/devices/{name}                     # de vez

action executa um passo sem stream ao vivo: open_app, close_app, url, tap, swipe, text, key, scroll, e os auxiliares de texto find_text, tap_text, wait_text, screen_text.

Rede

Todo aparelho tem uma saída de rede. GET /v1/network/options lista os tipos e países disponíveis agora.

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  # novo endereço, mesmo tipo e país
POST /v1/network/check                     {"url":"http://user:pass@198.51.100.24:8080"}

Fuso horário, idioma, chip e localização informada seguem a saída. A saída é aplicada abaixo do Android, o DNS passa por ela e o tráfego para se ela cair. Como funciona

Apps

Instale do nosso catálogo como um celular instala da Play Store, ou envie qualquer APK.

GET  /v1/apps                                # pacote, título, categoria, versão, tamanho
POST /v1/devices/{name}/apps  {"package":"com.instagram.android"}
GET  /v1/devices/{name}/apps                 # o que foi instalado do catálogo
curl -X POST https://api.clousd.com/v1/devices/{name}/apk \
  -H "Authorization: Bearer $CLOUSD_KEY" -F apk=@app-release.apk

As instalações do catálogo informam a Play Store como instaladora. Se a mesma versão ou uma mais nova já estiver instalada, a tarefa termina com “already”.

Snapshots e clones

Um snapshot congela o aparelho: apps, logins, arquivos e configurações. Restaure para voltar; clone para criar novos aparelhos com a mesma configuração e com número de série, IMEI, chip e Android ID próprios.

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"}

Os clones são aparelhos normais, cobrados como qualquer outro, e entram na lista da chave que os criou. Para backups com agenda, use Painel → Snapshots → Backup noturno.

Grupos e agendas

Uma tarefa de grupo roda uma lista de passos em vários aparelhos, e cada aparelho começa num momento aleatório dentro do intervalo que você definir. O progresso aparece por aparelho na tarefa.

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"}
  ]
}

Passos: open_app, close_app, install_app, url, tap, swipe, text, key, wait (aleatório entre seconds e seconds_max), browse (rolagens e pausas aleatórias, 10–600 s), scroll, if_text / unless_text (pula os próximos passos, a não ser que um texto esteja na tela), screenshot, start, stop, restart.

Uma agenda é a mesma tarefa com hora marcada: POST /v1/schedules com name, phones, steps, stagger, at ("HH:MM", UTC) e days (1–7). Pause com /toggle e remova com /delete. No painel, a Automação traz flows montados com blocos e ações prontas para os apps mais populares. O que é automatizado em cada app

Acesso ADB

O ADB vem desligado. Ative num aparelho, informando os endereços de onde você vai se conectar; você recebe um host, uma porta e um código de acesso único, mostrado uma 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                 # desligar, fechar sessões

Limites: allow_ips é obrigatório (até 20 IPs ou faixas); ttl_hours é 24 por padrão e no máximo 168; até 3 sessões por aparelho; 5 códigos errados fecham uma sessão, e 20 em 10 minutos desligam o relay; sessões ociosas fecham após 30 minutos; push e pull são limitados a 2 GiB por sessão. Root, remount, disable-verity, reverse, reboot, tcpip, usb, jdwp, sideload e restore são sempre recusados. Gerar um novo código fecha as sessões ativas.

Webhooks

Uma chave pode ter uma URL de webhook (defina ao criar a chave). Os eventos dos aparelhos da chave chegam como POST, com um corpo JSON {"event", "ts", "phone", "job" | "incident"}.

Cada requisição leva X-Clousd-Signature: o HMAC-SHA256 em hex do corpo bruto, com chave igual ao SHA-256 em hex da sua chave de API. A entrega é tentada três vezes: na hora, depois de 10 segundos e depois de 60 segundos, com timeout de 10 segundos.

Agentes de IA

Duas chamadas dão a um agente o seu ciclo: olhar e depois agir.

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 sempre tira uma captura de tela nova e devolve até 500 elementos da tela com os limites de cada um. act recusa com 409 stale se outro observe ou act aconteceu depois do seq que você passou, então um agente nunca age sobre uma imagem velha; com settle, ele espera a tela parar de mudar (até 5 s). Entre execuções, volte ao estado inicial restaurando um snapshot. Android para agentes de IA

Erros e limites

Os erros vêm em JSON, com um kind legível por máquina e uma mensagem: {"error": "busy", "message": "…"}. Códigos de status: 400 requisição inválida, 401 não autorizado, 402 saldo insuficiente, 403 proibido pelo escopo ou pela lista de aparelhos, 404 não encontrado, 409 ocupado ou desatualizado, 429 limite de requisições atingido.

Limites por chave: 60 requisições por minuto; nas rotas /devices/{name}/…, 120 por minuto por aparelho e 600 por minuto somando todos os aparelhos. Um 429 significa: diminua o ritmo e tente de novo com espera progressiva.

Equipe e chaves de API

Uma conta tem donos e operadores. Os donos cuidam da cobrança, das chaves de API, da equipe e da criação ou exclusão de aparelhos. Os operadores usam os aparelhos que você atribui: ligar, parar, apps, rede, snapshots e ADB, mas sem cobrança, chaves ou exclusão. Convide pessoas por e-mail em Equipe; elas entram para a equipe no primeiro login.

As chaves de API pertencem à conta, não a uma pessoa: cada chave tem um escopo (read ou control) e uma lista de aparelhos. Uma chave de leitura que chama uma rota de alteração recebe 403. Revogar uma chave a desativa na hora.

Cobrança

O Clousd funciona com saldo pré-pago. Recarregue a partir de $10 com cripto, WeChat Pay ou Alipay; cada recarga e cada cobrança vira uma linha em Cobrança, e Uso mostra minutos e custo por aparelho. Aparelhos por minuto consomem $0.004 por minuto enquanto estão ligados, nunca mais de $0.80 por dia; aparelhos mensais consomem $12.00 uma vez a cada 30 dias. O Android 15 acrescenta 10%, o Android 16, 25%, e o Android 17, 25%. As saídas de rede pagas são cobradas por gigabyte. Quando o saldo chega a zero, os aparelhos por minuto que estão ligados param e mantêm os dados. Preços

Como obter ajuda

Escreva para support@clousd.com ou use o formulário de contato; uma pessoa responde, normalmente em até um dia útil. Informe o ID do aparelho no painel (começa com dev_) ou o nome dele na API, e o que você esperava que acontecesse. O estado atual da plataforma está na página de status, e as mudanças recentes estão nas notas de versão.

Glossário

As palavras que o painel, a API e esta documentação usam, num só lugar.

Saída

O proxy aplicado a um aparelho, abaixo do Android: móvel, residencial, ISP, datacenter ou seu próprio proxy SOCKS5 ou HTTP. Os apps veem o endereço dela, e o fuso horário, o idioma e o chip seguem o país dela.

Região

Onde o aparelho roda. Escolha a mais perto de quem acompanha a tela ou usa o ADB; ela é escolhida à parte da saída de rede.

Snapshot

Uma cópia salva do aparelho inteiro: apps, logins, arquivos e configurações. Restaure em um passo ou clone novos aparelhos a partir dela.

Clonar

Um novo aparelho criado a partir de um snapshot: os mesmos apps, arquivos e configurações, com número de série, IMEI, chip, endereços de Wi-Fi e Bluetooth e Android ID próprios.

Identidade

Os identificadores de hardware que um aparelho informa: serial, IMEI, número de telefone e dados de Wi-Fi. Uma nova identidade substitui todos com uma chamada.

Receita

Uma automação pronta para uma ação num app, como Login, Aquecimento, Publicar post ou Excluir último post, rodada num celular, num grupo ou numa agenda.

Passos genéricos

Blocos que funcionam em qualquer app: abrir um app ou uma URL, tocar, deslizar, digitar texto, apertar uma tecla, navegar, rolar, esperar, conferir o texto na tela e tirar uma captura.

Flow

Uma sequência de passos montada com blocos em Automação, como Login, Aquecimento, Pausa e Publicar, cada um com duração e variação ±.

Grupo

Um conjunto de aparelhos em que você age de uma vez: ligar, parar, instalar apps e rodar passos, com intervalos aleatórios entre os celulares.

Agenda

Receitas ou passos que rodam por dia da semana e horário (UTC) num aparelho ou num grupo.

Recursos

Onde ficam contas e mídias: credenciais por conta, guardadas com criptografia e vinculadas a um celular, e a biblioteca Media.

Biblioteca Media

Pastas de fotos e vídeos no Resources. Os passos de publicação pegam o arquivo mais recente ou um aleatório e nunca repetem um arquivo no mesmo celular.

Multi-view e Sync

Uma parede de telas ao vivo, lado a lado. O Sync replica um toque, um deslize ou um texto digitado nos celulares que você selecionar.

Dono e operador

Funções da equipe. Os donos cuidam da cobrança, das chaves de API, da equipe e da criação ou exclusão de aparelhos; os operadores usam só os aparelhos atribuídos a eles.

Relay ADB

Como você chega a um aparelho com o adb: conecte-se ao relay e entre com um código único. Só os seus endereços IP, desligado por padrão, com prazo.