API do Virtualizor: criar, editar e apagar VPS

O ciclo de vida da VPS na conta Cloud: listar, ver os detalhes, criar dentro da cota, mudar recursos, apagar e configurar o escalonamento vertical.

Antes de começar, veja API do Virtualizor para revendedores: primeiros passos: lá estão a chave de API, o formato da chamada e as funções virt_api usadas nos exemplos em PHP, Python e Node.js.

Neste artigo

1. Listar as VPS — act=listvs
2. Ver os detalhes de uma VPS — act=vpsmanage
3. Criar uma VPS — act=create
4. Mudar os recursos de uma VPS — act=editvm
5. Apagar uma VPS — act=listvs
6. Configurar o escalonamento vertical — act=vpsmanage

Listar as VPS

Ação: act=listvs · Método: GET

Lista as VPS que a conta enxerga, com os recursos e o estado de cada uma.

Parâmetros

Nenhum além da ação e da autenticação.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=listvs&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS"

PHP

$r = virt_api('listvs');
print_r($r);

Python

r = virt_api("listvs")
print(r)

Node.js

const r = await virtApi('listvs');
console.log(r);

Resposta

As VPS indexadas pelo id (vpsid). Cada uma traz hostname, o dono (uid), o sistema (os_name, osid), a virtualização (virt), os recursos (ram, space, cores, bandwidth, swap), o estado de suspensão (suspended, nw_suspended, suspend_reason) e a configuração de VNC.

Cuidados

• Esta mesma ação, com parâmetros a mais na URL, apaga, suspende e reativa VPS (veja Apagar uma VPS e o artigo de energia e suspensão). Ao montar a URL no seu código, confira os parâmetros antes de chamar.

Documentação oficial: List VPS.

Ver os detalhes de uma VPS

Ação: act=vpsmanage · Método: GET

Devolve o estado e os detalhes de uma VPS: se está ligada, há quanto tempo, IPs, sistema e consumo de banda.

Parâmetros

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=vpsmanage&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS"

PHP

$r = virt_api('vpsmanage', [
    'svs' => '101',
]);
print_r($r);

Python

r = virt_api("vpsmanage", get={
    "svs": "101",
})
print(r)

Node.js

const r = await virtApi('vpsmanage', {
  svs: '101',
});
console.log(r);

Resposta

info traz hostname, status (ligada ou não), uptime, ip e ip_count, o sistema em os (nome, distribuição, osid) e bandwidth, com o limite, o usado e o consumo dia a dia.

Documentação oficial: VPS Info.

Criar uma VPS

Ação: act=create · Método: POST · Exclusivo do usuário Cloud

Cria uma VPS para um cliente, descontando os recursos da cota da sua conta Cloud. Sem addvs, nada é criado: a resposta traz os dados da tela de criação, como a cota livre e a lista de sistemas.

Parâmetros

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=create&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'addvs=1' \
  --data-urlencode 'virt=kvm' \
  --data-urlencode 'uid=25' \
  --data-urlencode 'hostname=vps1.exemplo.com.br' \
  --data-urlencode 'rootpass=Senha-Root-Forte-2026' \
  --data-urlencode 'osid=ID_DO_SISTEMA' \
  --data-urlencode 'space=20' \
  --data-urlencode 'ram=2048' \
  --data-urlencode 'cores=2' \
  --data-urlencode 'ips=1' \
  --data-urlencode 'bandwidth=0'

PHP

$r = virt_api('create', [], [
    'addvs' => '1',
    'virt' => 'kvm',
    'uid' => '25',
    'hostname' => 'vps1.exemplo.com.br',
    'rootpass' => 'Senha-Root-Forte-2026',
    'osid' => 'ID_DO_SISTEMA',
    'space' => '20',
    'ram' => '2048',
    'cores' => '2',
    'ips' => '1',
    'bandwidth' => '0',
]);
print_r($r);

Python

r = virt_api("create", post={
    "addvs": "1",
    "virt": "kvm",
    "uid": "25",
    "hostname": "vps1.exemplo.com.br",
    "rootpass": "Senha-Root-Forte-2026",
    "osid": "ID_DO_SISTEMA",
    "space": "20",
    "ram": "2048",
    "cores": "2",
    "ips": "1",
    "bandwidth": "0",
})
print(r)

Node.js

const r = await virtApi('create', {}, {
  addvs: '1',
  virt: 'kvm',
  uid: '25',
  hostname: 'vps1.exemplo.com.br',
  rootpass: 'Senha-Root-Forte-2026',
  osid: 'ID_DO_SISTEMA',
  space: '20',
  ram: '2048',
  cores: '2',
  ips: '1',
  bandwidth: '0',
});
console.log(r);

Resposta

vpsid é o id da VPS criada — guarde-o. A resposta também traz resources (a cota) e usage (o uso, já com a VPS nova), users e ostemplates.

Cuidados

• A documentação oficial não diz quais campos são obrigatórios nesta chamada. Os marcados como "sim" aqui são os que aparecem em todos os exemplos oficiais.
• Os recursos pedidos são conferidos contra a cota da conta, diz a documentação oficial. Consulte a cota antes de criar.
• O exemplo em curl da documentação oficial manda swap; a tabela e o exemplo em PHP usam swapram. Este artigo segue a tabela.
• A senha do root vai no corpo da chamada: use sempre HTTPS (porta 4083) e não registre o corpo em log.

Documentação oficial: Create VM.

Mudar os recursos de uma VPS

Ação: act=editvm · Método: POST · Exclusivo do usuário Cloud

Altera hostname, disco, RAM, núcleos, banda, IPs e VNC de uma VPS da conta. A diferença entra ou sai da cota.

Parâmetros

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=editvm&vid=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'editvm=1' \
  --data-urlencode 'uid=25' \
  --data-urlencode 'hostname=vps1.exemplo.com.br' \
  --data-urlencode 'space=40' \
  --data-urlencode 'ram=4096' \
  --data-urlencode 'cores=4' \
  --data-urlencode 'bandwidth=0' \
  --data-urlencode 'swapram=1024' \
  --data-urlencode 'vnc=1' \
  --data-urlencode 'ips=1'

PHP

$r = virt_api('editvm', [
    'vid' => '101',
], [
    'editvm' => '1',
    'uid' => '25',
    'hostname' => 'vps1.exemplo.com.br',
    'space' => '40',
    'ram' => '4096',
    'cores' => '4',
    'bandwidth' => '0',
    'swapram' => '1024',
    'vnc' => '1',
    'ips' => '1',
]);
print_r($r);

Python

r = virt_api("editvm", get={
    "vid": "101",
}, post={
    "editvm": "1",
    "uid": "25",
    "hostname": "vps1.exemplo.com.br",
    "space": "40",
    "ram": "4096",
    "cores": "4",
    "bandwidth": "0",
    "swapram": "1024",
    "vnc": "1",
    "ips": "1",
})
print(r)

Node.js

const r = await virtApi('editvm', {
  vid: '101',
}, {
  editvm: '1',
  uid: '25',
  hostname: 'vps1.exemplo.com.br',
  space: '40',
  ram: '4096',
  cores: '4',
  bandwidth: '0',
  swapram: '1024',
  vnc: '1',
  ips: '1',
});
console.log(r);

Resposta

done indica que a VPS foi alterada; done_msg traz a mensagem e vps os dados novos. resources e usage mostram a cota depois da mudança.

Cuidados

• A tabela oficial marca como obrigatórios hostname, disco, RAM, núcleos, banda, swap, VNC e IPs: mande todos, mesmo os que não mudam.
• O id da VPS vai na URL como vid — e não svs, como na maioria das outras ações. A tabela oficial também o lista no corpo; o exemplo dela manda só na URL, como aqui.
• O exemplo em curl da documentação oficial manda swap; a tabela e o exemplo em PHP usam swapram.
• Reduzir o disco de uma VPS em uso pode corromper o sistema de arquivos dela.

Documentação oficial: Edit VM.

Apagar uma VPS

Ação: act=listvs · Método: GET · Exclusivo do usuário Cloud

Apaga uma VPS de vez, com o disco, e devolve os recursos dela à cota.

Parâmetros

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=listvs&delvs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS"

PHP

$r = virt_api('listvs', [
    'delvs' => '101',
]);
print_r($r);

Python

r = virt_api("listvs", get={
    "delvs": "101",
})
print(r)

Node.js

const r = await virtApi('listvs', {
  delvs: '101',
});
console.log(r);

Resposta

done confirma; delvs repete o id apagado e vs traz a lista de VPS que sobrou.

Cuidados

• Não tem volta e não pede confirmação: é a mesma ação de listar VPS, com delvs na URL. Confira o id duas vezes no seu código.
• Faça backup antes, se o cliente puder querer os dados.
• A tabela oficial lista delvs como parâmetro POST; o exemplo oficial e o SDK mandam pela URL, como aqui.

Documentação oficial: Delete VM.

Configurar o escalonamento vertical

Ação: act=vpsmanage · Método: POST

Define de quanto em quanto a RAM e os núcleos da VPS sobem ou descem quando o escalonamento vertical age. Disponível a partir do Virtualizor 3.1.3.

Parâmetros

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=vpsmanage&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'save_ver_data=1' \
  --data-urlencode 'vs_ver_ram_inc_by=2' \
  --data-urlencode 'vs_ver_cpu_inc_by=1'

PHP

$r = virt_api('vpsmanage', [
    'svs' => '101',
], [
    'save_ver_data' => '1',
    'vs_ver_ram_inc_by' => '2',
    'vs_ver_cpu_inc_by' => '1',
]);
print_r($r);

Python

r = virt_api("vpsmanage", get={
    "svs": "101",
}, post={
    "save_ver_data": "1",
    "vs_ver_ram_inc_by": "2",
    "vs_ver_cpu_inc_by": "1",
})
print(r)

Node.js

const r = await virtApi('vpsmanage', {
  svs: '101',
}, {
  save_ver_data: '1',
  vs_ver_ram_inc_by: '2',
  vs_ver_cpu_inc_by: '1',
});
console.log(r);

Resposta

ver_done confirma que os dados foram gravados.

Cuidados

• O campo save_ver_data não aparece na tabela da documentação oficial, só no exemplo em curl dela. Sem ele, a chamada vira a de detalhes da VPS (act=vpsmanage) e nada é gravado.

Documentação oficial: Vertical Scaling Data.

Texto da Vitt Host, escrito a partir da documentação oficial da Virtualizor, lida em 07/10/2026. Onde a documentação oficial se contradiz, o artigo segue os exemplos dela e aponta a diferença em Cuidados.