Documentação da API — VPS por Hora (KVM)
Crie, consulte e destrua máquinas virtuais sob demanda com /dev/kvm (Nested Virtualization) habilitado e cobrança proporcional por tempo de uso.
Autenticação e Base URL
Todas as chamadas usam a Base URL https://yousecure.io e autenticam via cabeçalho
Authorization: Bearer SEU_TOKEN (ou X-API-Key: SEU_TOKEN).
| Plan ID | Configuração Base | Valor / Hora (Disco Base) | Valor / Hora (150 GB: 40 GB OS + 110 GB ZFS) |
|---|---|---|---|
starter |
2 vCPUs • 4 GB RAM • 30 GB SSD | R$ 0,10 / h | R$ 0,21 / h |
basic |
4 vCPUs • 8 GB RAM • 40 GB SSD | R$ 0,18 / h | R$ 0,28 / h |
performance |
6 vCPUs • 12 GB RAM • 60 GB SSD | R$ 0,29 / h | R$ 0,38 / h |
ultra |
8 vCPUs • 16 GB RAM • 80 GB SSD | R$ 0,42 / h | R$ 0,49 / h |
GET /api/v1/nested-kvm/balance
Consulta seu saldo atual de créditos em Reais (BRL), limite de VMs simultâneas e tabela de planos.
curl -s https://yousecure.io/api/v1/nested-kvm/balance \ -H "Authorization: Bearer SEU_TOKEN"
{
"account_id": "kvm_...",
"balance_brl": 2.0,
"max_vms": 4,
"default_os": "debian-13",
"images": {
"debian-13": { "id": "debian-13", "name": "Debian 13 (Trixie)", "default": true },
"ubuntu-24.04": { "id": "ubuntu-24.04", "name": "Ubuntu 24.04 LTS (Noble)", "default": false }
},
"plans": { ... }
}
POST /api/v1/nested-kvm/vms
Cria e inicia uma nova VM em ~15 segundos. Todos os recursos da máquina (sistema operacional, tamanho do disco, divisão de partição para ZFS, segundo disco dedicado e script Cloud-Init) são escolhidos diretamente no JSON da requisição:
| Campo JSON | Tipo | Padrão | Descrição |
|---|---|---|---|
vm_name |
string (obrigatório) | — | Nome único da sua VM (2 a 48 caracteres: letras, números, -, _ ou .). |
plan |
string | performance |
Plano de vCPU/RAM: starter, basic, performance ou ultra. |
os |
string | debian-13 |
Sistema operacional: debian-13 (Debian 13 Trixie) ou ubuntu-24.04 (Ubuntu 24.04 LTS). |
disk_gb |
integer | Disco base do plano (30–80 GB) | Tamanho total do disco principal /dev/vda (de 20 a 250 GB). Ex: 150 para 150 GB. Cobrança proporcional quando acima do disco base do plano. |
os_disk_gb |
integer | 40 (se disk_gb >= 80) ou 0 |
Reserva esse tamanho (ex: 40 GB) para o sistema em /dev/vda1 e cria automaticamente uma partição vazia /dev/vda2 (tipo GPT ZFS) com o espaço restante (ex: 110 GB livres em um disco de 150 GB). Envie 0 para o sistema ocupar 100% do disco. |
zfs_disk_gb |
integer | 0 |
Opcional: anexa um 2º disco VirtIO separado e 100% vazio em /dev/vdb (de 5 a 200 GB). |
user_data |
string | — | Opcional: Cloud-Init customizado (deve iniciar com #cloud-config ou #!/), aceito em texto puro ou codificado em Base64 (máx. 32 KB). |
ssh_pubkey |
string | Chave da conta | Chave pública SSH (ssh-ed25519, ssh-rsa ou ecdsa) injetada no usuário root. |
curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vm_name": "worker-01",
"plan": "basic",
"os": "debian-13",
"disk_gb": 150,
"os_disk_gb": 40,
"user_data": "#cloud-config\nruncmd:\n - echo pronto > /root/ready.txt",
"ssh_pubkey": "ssh-ed25519 AAAA... seu-usuario@host"
}'
{
"vm_name": "worker-01",
"plan": "basic",
"os": "debian-13",
"vcpus": 4,
"ram_gb": 8,
"disk_gb": 150,
"os_disk_gb": 40,
"zfs_partition_gb": 110,
"extra_disk_gb": 0,
"hourly_rate_brl": 0.28,
"private_ip": "192.168.122.45",
"ssh_host": "178.83.141.102",
"ssh_port": 22045,
"ssh_command": "ssh -p 22045 [email protected]",
"status": "running"
}
Dica: após o retorno, aguarde ~10 segundos para o Cloud-Init aplicar sua chave SSH e conecte com o comando retornado em ssh_command. Dentro da VM, ls -l /dev/kvm já estará disponível.
GET /api/v1/nested-kvm/vms
Lista todas as suas VMs em execução, seus IPs privados, portas SSH públicas e o valor acumulado já debitado.
curl -s https://yousecure.io/api/v1/nested-kvm/vms \ -H "Authorization: Bearer SEU_TOKEN"
GET /api/v1/nested-kvm/vms/<vm_name>
Consulta o estado em tempo real de uma VM específica no hypervisor e atualiza o IP/porta caso tenha acabado de subir.
curl -s https://yousecure.io/api/v1/nested-kvm/vms/worker-01 \ -H "Authorization: Bearer SEU_TOKEN"
POST /api/v1/nested-kvm/vms/<vm_name>/stop
Desliga a VM preservando todo o disco (inclusive dados, ZFS e boxes). Enquanto desligada, zera a cobrança de vCPU/RAM e passa a cobrar apenas pelo espaço real ocupado em disco (thin-provisioned em qcow2, R$ 0,001/GB usado/hora — ex.: 10 GB usados custam apenas R$ 0,01/h).
curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms/worker-01/stop \ -H "Authorization: Bearer SEU_TOKEN"
{
"vm_name": "worker-01",
"status": "stopped",
"used_disk_gb": 10.45,
"stopped_hourly_rate_brl": 0.0105,
"charged_brl": 0.0412,
"balance_brl": 1.9588
}
POST /api/v1/nested-kvm/vms/<vm_name>/start
Religa uma VM que estava em stopped mantendo todo o disco intacto, reabrindo a porta SSH e retomando a tarifa normal do plano.
curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms/worker-01/start \ -H "Authorization: Bearer SEU_TOKEN"
{
"vm_name": "worker-01",
"status": "running",
"hourly_rate_brl": 0.49,
"private_ip": "192.168.122.230",
"ssh_host": "178.83.141.102",
"ssh_port": 22230,
"ssh_command": "ssh -p 22230 [email protected]"
}
DELETE /api/v1/nested-kvm/vms/<vm_name>
Destrói a VM imediatamente, remove o disco efêmero, fecha o redirecionamento de porta e encerra a cobrança por hora (respeitando o piso mínimo de 5 minutos por criação).
curl -s -X DELETE https://yousecure.io/api/v1/nested-kvm/vms/worker-01 \ -H "Authorization: Bearer SEU_TOKEN"
{
"vm_name": "worker-01",
"status": "destroyed",
"charged_brl": 0.0292,
"balance_brl": 1.9708
}