API do Virtualizor: hostname, senha root, reinstalação e receitas

Ajustes dentro da VPS: hostname, senha do root, configurações da máquina virtual, reinstalação do sistema, instalação de painel e de aplicações, e execução de receitas (scripts de pós-instalação).

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

Trocar o hostname — act=hostname
Trocar a senha do root — act=changepassword
Alterar ordem de boot, placa de rede e opções da VM — act=hvmsettings
Reinstalar o sistema operacional — act=ostemplate
Instalar um painel de controle — act=controlpanel
Listar as aplicações do Webuzo — act=webuzo
Listar as receitas — act=listrecipes
Executar uma receita — act=listrecipes

Trocar o hostname

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

Muda o hostname da VPS.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`changehost`	corpo (POST)	1	sim	Confirma a troca.
`newhost`	corpo (POST)	texto	sim	Hostname novo.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=hostname&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'changehost=1' \
  --data-urlencode 'newhost=vps1.exemplo.com.br'

PHP

$r = virt_api('hostname', [
    'svs' => '101',
], [
    'changehost' => '1',
    'newhost' => 'vps1.exemplo.com.br',
]);
print_r($r);

Python

r = virt_api("hostname", get={
    "svs": "101",
}, post={
    "changehost": "1",
    "newhost": "vps1.exemplo.com.br",
})
print(r)

Node.js

const r = await virtApi('hostname', {
  svs: '101',
}, {
  changehost: '1',
  newhost: 'vps1.exemplo.com.br',
});
console.log(r);

Resposta

done confirma e current mostra o hostname em vigor. Se a mudança não aparecer com a VPS ligada, reinicie-a.

Cuidados

O campo changehost não está na tabela da documentação oficial, só no exemplo dela. Sem ele, a chamada só lê o hostname.

Documentação oficial: Change Hostname.

Trocar a senha do root

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

Troca a senha do root dentro da VPS.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`changepass`	corpo (POST)	1	sim	Confirma a troca.
`newpass`	corpo (POST)	texto	sim	Senha nova.
`conf`	corpo (POST)	texto	sim	A mesma senha, para confirmar.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=changepassword&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'changepass=1' \
  --data-urlencode 'newpass=Nova-Senha-Root-2026' \
  --data-urlencode 'conf=Nova-Senha-Root-2026'

PHP

$r = virt_api('changepassword', [
    'svs' => '101',
], [
    'changepass' => '1',
    'newpass' => 'Nova-Senha-Root-2026',
    'conf' => 'Nova-Senha-Root-2026',
]);
print_r($r);

Python

r = virt_api("changepassword", get={
    "svs": "101",
}, post={
    "changepass": "1",
    "newpass": "Nova-Senha-Root-2026",
    "conf": "Nova-Senha-Root-2026",
})
print(r)

Node.js

const r = await virtApi('changepassword', {
  svs: '101',
}, {
  changepass: '1',
  newpass: 'Nova-Senha-Root-2026',
  conf: 'Nova-Senha-Root-2026',
});
console.log(r);

Resposta

done confirma a troca.

Cuidados

O campo changepass não está na tabela da documentação oficial, só no exemplo dela.
Se a senha nova não funcionar com a VPS ligada, reinicie-a.

Documentação oficial: Change Password.

Alterar ordem de boot, placa de rede e opções da VM

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

Ajusta a máquina virtual: ordem de boot, ISO montada, modelo da placa de rede, teclado do VNC e opções como ACPI e aceleração de vídeo. Sem hvmsettings, a chamada devolve as opções aceitas.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`hvmsettings`	corpo (POST)	1	sim	Confirma a gravação.
`boot`	corpo (POST)	texto	sim	Ordem de boot em letras: `c` é o disco e `d` a ISO (CD-ROM). `cd` dá boot pelo disco primeiro; `dc`, pela ISO.
`nic_type`	corpo (POST)	texto	sim	Modelo da placa de rede. Os aceitos vêm em `nictypes` na resposta.
`hvm_vnc_keymap`	corpo (POST)	texto	não	Layout de teclado do console VNC, como `pt-br` ou `en-us`. Os aceitos vêm em `vnckeymaps`.
`acpi`	corpo (POST)	0 ou 1	não	Liga o ACPI, que permite o desligamento normal pelo painel.
`apic`	corpo (POST)	0 ou 1	não	Liga o APIC.
`vnc`	corpo (POST)	0 ou 1	não	Liga ou desliga o console VNC.
`kvm_vga`	corpo (POST)	0 ou 1	não	Liga a placa de vídeo VGA (KVM).
`acceleration`	corpo (POST)	0 ou 1	não	Liga a aceleração de vídeo 2D e 3D.
`isos`	corpo (POST)	texto	não	Nome da ISO a montar, da lista em `isos`.
`sec_iso`	corpo (POST)	texto	não	Segunda ISO.
`tuntap_enable`	corpo (POST)	0 ou 1	não	Liga TUN/TAP. Só OpenVZ.
`ppp_enable`	corpo (POST)	0 ou 1	não	Liga PPP. Só OpenVZ.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=hvmsettings&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'hvmsettings=1' \
  --data-urlencode 'boot=cd' \
  --data-urlencode 'nic_type=e1000' \
  --data-urlencode 'hvm_vnc_keymap=pt-br' \
  --data-urlencode 'acpi=1' \
  --data-urlencode 'apic=1'

PHP

$r = virt_api('hvmsettings', [
    'svs' => '101',
], [
    'hvmsettings' => '1',
    'boot' => 'cd',
    'nic_type' => 'e1000',
    'hvm_vnc_keymap' => 'pt-br',
    'acpi' => '1',
    'apic' => '1',
]);
print_r($r);

Python

r = virt_api("hvmsettings", get={
    "svs": "101",
}, post={
    "hvmsettings": "1",
    "boot": "cd",
    "nic_type": "e1000",
    "hvm_vnc_keymap": "pt-br",
    "acpi": "1",
    "apic": "1",
})
print(r)

Node.js

const r = await virtApi('hvmsettings', {
  svs: '101',
}, {
  hvmsettings: '1',
  boot: 'cd',
  nic_type: 'e1000',
  hvm_vnc_keymap: 'pt-br',
  acpi: '1',
  apic: '1',
});
console.log(r);

Resposta

done confirma. boot, vnckeymaps, nictypes, isos e oslist trazem as opções aceitas, e vps a configuração atual.

Cuidados

A tabela da documentação oficial e os exemplos dela divergem nos nomes: nictype × nic_type, enable_tuntap_cp × tuntap_enable, enable_ppp_cp × ppp_enable; e acpi, apic, vnc e kvm_vga só aparecem nos exemplos. Este artigo segue os exemplos.
Mudar a placa de rede ou a ordem de boot em VPS ligada só vale no próximo boot.

Documentação oficial: VPS Configuration.

Reinstalar o sistema operacional

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

Reinstala a VPS com o mesmo sistema ou com outro. Sem reinsos, a chamada devolve a lista de sistemas disponíveis.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`reinsos`	corpo (POST)	1	sim	Confirma a reinstalação.
`newos`	corpo (POST)	número	sim	Id do sistema (`osid`), da lista em `oslist`.
`newpass`	corpo (POST)	texto	sim	Senha do root da instalação nova.
`conf`	corpo (POST)	texto	sim	A mesma senha, para confirmar.
`rebuild_sshkey`	corpo (POST)	texto	não	Chave pública SSH a instalar no sistema novo.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=ostemplate&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'reinsos=1' \
  --data-urlencode 'newos=ID_DO_SISTEMA' \
  --data-urlencode 'newpass=Senha-Root-Nova-2026' \
  --data-urlencode 'conf=Senha-Root-Nova-2026'

PHP

$r = virt_api('ostemplate', [
    'svs' => '101',
], [
    'reinsos' => '1',
    'newos' => 'ID_DO_SISTEMA',
    'newpass' => 'Senha-Root-Nova-2026',
    'conf' => 'Senha-Root-Nova-2026',
]);
print_r($r);

Python

r = virt_api("ostemplate", get={
    "svs": "101",
}, post={
    "reinsos": "1",
    "newos": "ID_DO_SISTEMA",
    "newpass": "Senha-Root-Nova-2026",
    "conf": "Senha-Root-Nova-2026",
})
print(r)

Node.js

const r = await virtApi('ostemplate', {
  svs: '101',
}, {
  reinsos: '1',
  newos: 'ID_DO_SISTEMA',
  newpass: 'Senha-Root-Nova-2026',
  conf: 'Senha-Root-Nova-2026',
});
console.log(r);

Resposta

done confirma que a reinstalação começou. oslist e distros trazem os sistemas disponíveis.

Cuidados

Apaga tudo o que está no disco da VPS. Faça backup antes.
A VPS pode ter limite de reinstalações (osreinstall_limit, definido na criação).
A tabela oficial também lista o id da VPS como vid no corpo; o exemplo dela usa só svs na URL, como aqui.

Documentação oficial: OS Reinstall.

Instalar um painel de controle

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

Instala um painel de hospedagem dentro da VPS.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`ins`	corpo (POST)	texto	sim	Painel a instalar. A documentação oficial não lista os valores aceitos; o exemplo dela usa `plesk`.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=controlpanel&svs=101&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'ins=plesk'

PHP

$r = virt_api('controlpanel', [
    'svs' => '101',
], [
    'ins' => 'plesk',
]);
print_r($r);

Python

r = virt_api("controlpanel", get={
    "svs": "101",
}, post={
    "ins": "plesk",
})
print(r)

Node.js

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

Resposta

done confirma que a instalação começou.

Cuidados

A tabela oficial descreve ins como 1 ou 0, mas o exemplo dela manda o nome do painel. Este artigo segue o exemplo.
Instalar painel numa VPS que já tem serviços rodando pode conflitar com eles. Prefira VPS recém-instalada.

Documentação oficial: Control Panel.

Listar as aplicações do Webuzo

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

Lista as aplicações que o Webuzo instala na VPS e se o Webuzo está liberado para ela.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.

Exemplos

curl

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

PHP

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

Python

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

Node.js

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

Resposta

webuzo_apps traz as aplicações; webuzo_enabled diz se o recurso está liberado; info traz dados da VPS.

Cuidados

A URL de exemplo da documentação oficial carrega novnc e do=add, sobras de outra página. Não são necessários.

Documentação oficial: Webuzo Scripts.

Listar as receitas

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

Lista as receitas disponíveis para a VPS. Receita é um script que o Virtualizor roda dentro da VPS — para instalar um painel, configurar o firewall ou subir uma aplicação.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.

Exemplos

curl

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

PHP

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

Python

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

Node.js

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

Resposta

recipes traz as receitas, com o id de cada uma (o que se usa para executar).

Cuidados

A tabela oficial também lista o id da VPS como vid no corpo; o exemplo dela usa só svs na URL, como aqui.

Documentação oficial: List Recipes.

Executar uma receita

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

Executa uma ou mais receitas dentro da VPS.

Parâmetros

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`svs`	URL	número	sim	Id da VPS.
`rid`	URL	número	sim	Id da receita.
`exec_recipe`	corpo (POST)	1	sim	Confirma a execução.
`exec_rid`	corpo (POST)	número	sim	Id da receita, de novo, no corpo.

Exemplos

curl

curl -sS "https://$VIRT_HOST:4083/index.php?act=listrecipes&svs=101&rid=9&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS" \
  --data-urlencode 'exec_recipe=1' \
  --data-urlencode 'exec_rid=9'

PHP

$r = virt_api('listrecipes', [
    'svs' => '101',
    'rid' => '9',
], [
    'exec_recipe' => '1',
    'exec_rid' => '9',
]);
print_r($r);

Python

r = virt_api("listrecipes", get={
    "svs": "101",
    "rid": "9",
}, post={
    "exec_recipe": "1",
    "exec_rid": "9",
})
print(r)

Node.js

const r = await virtApi('listrecipes', {
  svs: '101',
  rid: '9',
}, {
  exec_recipe: '1',
  exec_rid: '9',
});
console.log(r);

Resposta

done confirma que a execução começou; recipes traz a lista de receitas.

Cuidados

A documentação oficial é contraditória aqui: a tabela pede rid no corpo (aceitando uma lista de ids), e o exemplo manda rid na URL e exec_rid no corpo. Este artigo segue o exemplo, que é o que tem a chamada completa.
A receita é um script executado dentro da VPS. Execute só receitas que você conhece.

Documentação oficial: Execute Recipe.

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.

Neste artigo

Trocar o hostname

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Trocar a senha do root

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Alterar ordem de boot, placa de rede e opções da VM

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Reinstalar o sistema operacional

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Instalar um painel de controle

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Listar as aplicações do Webuzo

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Listar as receitas

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Executar uma receita

Parâmetros

Exemplos

curl

PHP

Python

Node.js

Resposta

Cuidados

Hosting

Empresa

Outras páginas