Início rápido da API de VPS: crie a chave de API e o primeiro servidor

Passo 2. Autenticação e primeira requisição

Todas as requisições vão para o endereço base https://helpervps.com/api/v1, com o cabeçalho Authorization: Bearer chave. Como primeira requisição, traga a lista dos seus servidores. Se não houver servidores, volta uma lista vazia [].

curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Cada conta pode enviar até 300 requisições por minuto, e a criação de servidores vai até 10 vezes a cada 10 minutos. Para requisições repetidas de verificação de estado, alguns segundos de intervalo bastam. Todas as respostas são JSON, e os erros voltam com o código de estado no formato {"error": "code"}.

Passo 3. Escolher configuração, região e imagem

Todos os valores usados na criação de servidores vêm do catálogo. GET /catalog devolve de uma vez as configurações à venda (plans), as regiões (locations), as imagens (images) e as opções adicionais (addons). Com jq, fica fácil ver só a parte necessária.

curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'

• Código de configuração: indica tipo e tamanho, como s1 e s2. O type é basic (SSD padrão), fast (NVMe de alto desempenho), cpu (CPU dedicada) ou mem (alta memória). O monthly é a mensalidade em dólares americanos.
• Código de região: nomes de cidades, como frankfurt, singapore e seoul.
• Código de imagem: sistemas operacionais como ubuntu-24-04, debian-13 e almalinux-10 e apps como app-docker e app-wordpress.
• Opções adicionais: porcentagem do backup automático, tamanhos e preço por GB do disco adicional e preço da proteção DDoS. Opções não vendidas vêm como null.

Se não tiver o jq, instale com apt install -y jq no Ubuntu e brew install jq no Mac. É a mesma lista que você escolhe na tela, então é prático ver junto as diferenças por configuração na página de preços.

Passo 4. Criar um servidor

Envie o plano, localização, imagem e nome como JSON para POST /servers. Pague pelo primeiro período do plano escolhido e a criação do servidor começará.

curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

Se der certo, volta o código de estado 201 com os dados do servidor. O id é o código do servidor no formato S-XXXX-XXXX-XXXX, usado em todas as requisições seguintes. O root_password vem uma única vez nesta resposta, então guarde-o na hora. Também pode vê-lo na página do servidor por 7 dias.

• label: é o nome do servidor. Use letras, números, pontos e hifens até 40 caracteres; outros caracteres viram hifens.
• backups: com true, o backup automático é ativado.
• extra_disk_gb: é o tamanho do disco de blocos NVMe adicional. Coloque um dos valores sizes_gb do catálogo (50, 100, 250, 500, 1000).
• ddos_protection: com true, a proteção DDoS é ativada.

O preço das opções soma-se à mensalidade do servidor, aparece no monthly da resposta e é renovado automaticamente pelo mesmo valor em cada data de cobrança. Cada conta pode criar até 10 servidores.

Passo 5. Verificar o estado e acessar

O novo servidor começa no estado creating, passa a running quando está pronto e o endereço ipv4 é preenchido. O laço abaixo confere o estado a cada 10 segundos e mostra o IP quando fica running. Troque o código do servidor pelo do seu servidor.

ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

O status pode ser creating, running, stopped, rebooting, installing, suspended ou check. suspended significa que o servidor foi pausado porque não foi renovado na data de faturamento, e check significa que estamos verificando o resultado da configuração do servidor. Quando o IP aparecer, conecte-se com ssh root@IP. Como conectar está no guia de primeiro login.

Passo 6. Energia, renovação e exclusão

curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"

• start: liga um servidor parado (stopped).
• stop, reboot: desliga ou reinicia um servidor em execução (running).
• renew: paga por 1, 3, 6 ou 12 meses adicionais agora. Um servidor suspenso também volta com esta solicitação.
• DELETE: exclui o servidor e o disco e devolve {"state": "deleted"}. O tempo restante do mês já pago não é reembolsado.

Se enviar uma operação impossível no estado atual, volta 409 wrong_state. Por exemplo, ao enviar start para um servidor já ligado. A reinstalação e a geração de nova senha de root são feitas na página do servidor. A ordem está no guia de reinstalação.

Executar os mesmos passos com Python

O mesmo fluxo escrito em um script Python fica assim. Usa a biblioteca requests (pip install requests).

import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Códigos de erro mais comuns

• 401 unauthorized: a chave falta ou está errada. Confira se o cabeçalho tem o formato Authorization: Bearer hvp_....
• 403 not_allowed: liberado após a confirmação do seu primeiro pagamento.
• 400 bad_request: o nome ou o valor de um campo está errado. Use os códigos tal como estão no catálogo.
• 402 not_enough_balance: o valor do pagamento é inferior a $25. Envie novamente com pelo menos $25.
• 409 limit: a conta chegou ao número máximo de servidores.
• 409 not_created: o servidor não pôde ser criado, e a taxa é devolvida ao crédito da sua conta.
• 202 checking: estamos verificando o resultado da configuração do servidor. Não envie a mesma solicitação novamente; verifique sua lista de servidores. O servidor será concluído ou a taxa será devolvida ao crédito da sua conta.
• 404 not_found: é um código de servidor ou endereço que não existe na sua conta.
• 409 wrong_state: é uma operação impossível no estado atual.
• 429 rate_limited: chegou ao limite de requisições por minuto. Espere um pouco e envie.

Todos os endpoints, campos de resposta e exemplos estão reunidos na documentação da API. O que dá para fazer com a API e seus usos estão na página API de VPS.