> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/es/automation-api/vm-creation-api.md).

# API de creación de VM

{% hint style="info" %}
**Puntos clave**

* Crea VMs con parámetros esenciales de configuración usando la API REST
* Compatibilidad con la creación de VMs basada en recetas con configuraciones complejas
* Agrega unidades, dispositivos e interfaces de red después de crear la VM
* Comprende las diferencias entre clave de VM y clave de máquina para distintas operaciones
  {% endhint %}

Esta guía cubre la creación de máquinas virtuales en VergeOS, desde la creación básica de VM hasta la adición de unidades, dispositivos e interfaces de red. La API de VergeOS proporciona endpoints completos para la creación de VM y la configuración de hardware.

**Etapa**: Creación de VM (1 de 4) **Entrada**: credenciales de API, información del clúster, especificaciones de la VM **Salida**: clave de VM (42) + clave de máquina (54) **Siguiente**: usa las claves para la gestión de energía **Siguientes pasos comunes**:

* Encender VM → [`Gestión de energía de la VM`](/knowledge-base/es/automation-api/vm-power-management.md)
* Configurar ajustes → [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md)
* Operaciones avanzadas → [`Operaciones avanzadas de VM`](/knowledge-base/es/automation-api/vm-advanced-operations.md)

## Este documento ayuda con

* "Cómo crear una VM mediante la API"
* "Cómo agregar unidades durante la configuración de la VM"
* "Cómo adjuntar dispositivos GPU/PCI a las VMs"
* "Creación de VM con cloud-init"
* "Comprender las claves de VM frente a las de máquina"
* "Cómo configurar interfaces de red para nuevas VMs"
* "Provisionamiento de VM basado en recetas"
* "Automatización de creación masiva de VMs"
* "Despliegue de VMs como código de infraestructura"

## Referencia rápida

### Puntos finales principales

* **Crear VM**: `POST /api/v4/vms`
* **Agregar unidad**: `POST /api/v4/machine_drives`
* **Agregar dispositivo**: `POST /api/v4/machine_devices`
* **Agregar NIC**: `POST /api/v4/machine_nics`

### Parámetros clave

* `name`: identificador de la VM (obligatorio)
* `cluster`: ID del clúster de destino
* `machine`: ID de la máquina de la creación de la VM (para añadir hardware)
* `resource_group`: UUID para passthrough de dispositivos

### Autenticación

```bash
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
```

### Siguientes pasos

Después de crear la VM → Gestión de energía ([`Gestión de energía de la VM`](/knowledge-base/es/automation-api/vm-power-management.md))

## Referencia rápida de la API

| Operación           | Método | Punto final                   | Tipo de clave    | Propósito              |
| ------------------- | ------ | ----------------------------- | ---------------- | ---------------------- |
| Crear VM            | POST   | `/api/v4/vms`                 | Devuelve ambas   | Creación inicial       |
| Agregar unidad      | POST   | `/api/v4/machine_drives`      | Clave de máquina | Hardware               |
| Agregar dispositivo | POST   | `/api/v4/machine_devices`     | Clave de máquina | passthrough de GPU/PCI |
| Agregar NIC         | POST   | `/api/v4/machine_nics`        | Clave de máquina | Interfaz de red        |
| Encendido           | POST   | `/api/v4/vm_actions`          | clave de VM      | Control                |
| Comprobar estado    | GET    | `/api/v4/machine_status/{id}` | Clave de máquina | Monitorear             |

## Índice de resolución de problemas

* **409 Conflicto**: el nombre de la VM ya existe, ya está en ejecución, permiso denegado
* **400 Solicitud incorrecta**: parámetros inválidos, faltan campos obligatorios, JSON inválido
* **507 Almacenamiento insuficiente**: nivel lleno, reduce el tamaño, elige un nivel diferente
* **403 Prohibido**: permisos de la clave API, acceso al clúster denegado
* **404 No encontrado**: ID de clúster inválido, falta la fuente de medios, grupo de recursos inválido
* **422 Entidad no procesable**: interfaz de unidad inválida, tipo de medio no compatible

## Requisitos previos

* Credenciales válidas de la API de VergeOS con permisos de gestión de VM
* Comprensión de los conceptos de VergeOS: clústeres, vnets, fuentes de medios y grupos de recursos
* Conocimientos básicos de los principios de API REST y del formato JSON

## Autenticación

Todas las operaciones de creación de VM requieren autenticación usando una de las siguientes opciones:

* **Clave API**: inclúyela en el `Authorization` encabezado como `Bearer YOUR_API_KEY`
* **Autenticación básica**: nombre de usuario y contraseña para sesiones interactivas
* **Token de sesión**: para integraciones basadas en web

```bash
# Uso de clave API
curl -H "Authorization: Bearer YOUR_API_KEY" \\
     -H "Content-Type: application/json" \\
     https://your-vergeos.example.com/api/v4/vms
```

## Creación básica de VM

### POST /api/v4/vms

**Descripción**: crea una nueva máquina virtual con la configuración especificada.

**Parámetros de la solicitud**:

| Nombre              | Tipo   | Obligatorio | Descripción                                                     |
| ------------------- | ------ | ----------- | --------------------------------------------------------------- |
| name                | cadena | Sí          | Nombre único de la VM                                           |
| description         | cadena | No          | Descripción de la VM                                            |
| cluster             | cadena | No          | ID del clúster de destino (cadena numérica)                     |
| ram                 | entero | No          | RAM en MB (predeterminado: 1024)                                |
| cpu\_cores          | entero | No          | Número de núcleos de CPU (predeterminado: 1)                    |
| guest\_agent        | cadena | No          | Habilitar el agente invitado ("true"/"false")                   |
| console\_pass\_hash | cadena | No          | Hash de la contraseña de la consola (cadena vacía si no se usa) |
| video               | cadena | No          | Tipo de adaptador de video (virtio, std, cirrus, etc.)          |
| rtc\_base           | cadena | No          | Configuración base del RTC (utc, localtime)                     |
| uefi                | cadena | No          | Habilitar arranque UEFI ("true"/"false")                        |

**Ejemplo del cuerpo de la solicitud**:

```json
{
  "name": "web-server-01",
  "description": "Servidor web de producción",
  "cluster": "1",
  "ram": 8192,
  "cpu_cores": 4,
  "guest_agent": "true",
  "console_pass_hash": "",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true"
}
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/vms/42",
  "dbpath": "vms/42",
  "$row": 42,
  "$key": "42",
  "response": {
    "machine": "54"
  }
}
```

**Campos de respuesta**:

| Campo            | Tipo   | Descripción                                                |
| ---------------- | ------ | ---------------------------------------------------------- |
| location         | cadena | Punto final de la API para la VM creada                    |
| dbpath           | cadena | Ruta de base de datos para el registro de la VM            |
| $row             | entero | Número de fila de la base de datos                         |
| $key             | cadena | ID de la VM (usado para llamadas posteriores a la API)     |
| response.machine | cadena | ID de la máquina (usado para unidades, NIC y dispositivos) |

**Respuestas de error**:

* `400 Solicitud incorrecta`: parámetros de configuración inválidos
* `409 Conflicto`: el nombre de la VM ya existe
* `403 Prohibido`: permisos insuficientes

{% hint style="success" %}
**Clave de VM frente a clave de máquina**

* **clave de VM** (p. ej., "42"): úsala para ajustes de la VM como CPU, RAM y consola
* **Clave de máquina** (p. ej., "54"): úsala para hardware como unidades, NIC y dispositivos
* Obtienes ambas claves en la respuesta de creación de la VM
  {% endhint %}

## Creación de VM basada en recetas

VergeOS admite la creación compleja de VMs usando recetas que incluyen unidades, interfaces de red y dispositivos.

### VM completa con configuración de receta

```json
{
  "name": "enterprise-vm",
  "description": "Servidor de aplicaciones empresarial",
  "cluster": "1",
  "cpu_cores": 8,
  "ram": 16384,
  "guest_agent": "true",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true",
  "secure_boot": "true",
  "console_pass_hash": "",
  "cloudinit_datasource": "nocloud",
  "cloudinit_files": [
    {
      "name": "user-data",
      "contents": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-rsa AAAAB3NzaC1yc2E..."
    },
    {
      "name": "meta-data",
      "contents": "instance-id: enterprise-vm-001\nlocal-hostname: enterprise-vm"
    }
  ]
}
```

## Agregar unidades

Las unidades deben crearse por separado después de crear la VM usando el endpoint de unidades de máquina.

### POST /api/v4/machine\_drives

**Parámetros de la solicitud**:

| Nombre          | Tipo   | Obligatorio | Descripción                                                                                        |
| --------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- |
| machine         | cadena | Sí          | ID de la máquina de la creación de la VM                                                           |
| name            | cadena | No          | Nombre de la unidad                                                                                |
| medio           | cadena | No          | Tipo de medio (disco, cdrom, import, clone, efidisk)                                               |
| interfaz        | cadena | No          | Interfaz de la unidad (virtio-scsi, ide, ahci, etc.)                                               |
| disksize        | entero | No          | Tamaño del disco en bytes (para discos nuevos)                                                     |
| preferred\_tier | cadena | No          | Nivel de almacenamiento (1-5)                                                                      |
| media\_source   | cadena | No          | ID del medio de origen (para importación/clonación/cdrom)                                          |
| show\_pt        | cadena | No          | Anular nivel preferido ("true"/"false") - reemplaza el nivel predeterminado de la fuente de medios |

### Creación de una unidad de arranque

```json
{
  "machine": "54",
  "name": "Unidad de SO",
  "media": "disk",
  "interface": "virtio-scsi",
  "disksize": 2199023255552,
  "preferred_tier": "1"
}
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/machine_drives/54",
  "dbpath": "machine_drives/54",
  "$row": 54,
  "$key": "54"
}
```

### Adjuntar CDROM/ISO

```json
{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/machine_drives/55",
  "dbpath": "machine_drives/55",
  "$row": 55,
  "$key": "55"
}
```

### Importando desde la fuente de medios

```json
{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}
```

## Agregar dispositivos (GPU, passthrough PCI, etc.)

### POST /api/v4/machine\_devices

**Descripción**: adjunta dispositivos de hardware como GPU, dispositivos PCI, dispositivos USB o TPM a una máquina virtual.

**Parámetros de la solicitud**:

| Nombre          | Tipo   | Obligatorio | Descripción                                                                     |
| --------------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| machine         | cadena | Sí          | ID de máquina                                                                   |
| resource\_group | cadena | Sí          | UUID del grupo de recursos para el dispositivo                                  |
| settings\_args  | objeto | No          | Configuración específica del dispositivo (objeto vacío para passthrough básico) |

### GPU con passthrough PCI

```json
{
  "machine": "54",
  "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
  "settings_args": {}
}
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/machine_devices/2",
  "dbpath": "machine_devices/2",
  "$row": 2,
  "$key": "2",
  "response": {
    "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba"
  }
}
```

{% hint style="success" %}
**Encontrar grupos de recursos**

El `resource_group` parámetro identifica el dispositivo de hardware específico que se va a adjuntar. Usa estos puntos finales para encontrar los UUID de grupos de recursos disponibles:

* `GET /api/v4/resource_groups` - Dispositivos de hardware generales (GPU, dispositivos PCI, USB, etc.)
* `GET /api/v4/node_nvidia_vgpu_devices` - Dispositivos NVIDIA vGPU específicamente
  {% endhint %}

### Encontrar dispositivos disponibles

```bash
# Dispositivos de hardware generales
curl "https://your-vergeos.example.com/api/v4/resource_groups" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Dispositivos NVIDIA vGPU
curl "https://your-vergeos.example.com/api/v4/node_nvidia_vgpu_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Agregar interfaces de red

### POST /api/v4/machine\_nics

**Parámetros de la solicitud**:

| Nombre     | Tipo     | Obligatorio | Descripción                                    |
| ---------- | -------- | ----------- | ---------------------------------------------- |
| machine    | cadena   | Sí          | ID de máquina                                  |
| vnet       | cadena   | Sí          | ID de red virtual (clave de la red de destino) |
| name       | cadena   | No          | Nombre de la NIC                               |
| interfaz   | cadena   | No          | Tipo de interfaz de NIC (virtio, e1000, etc.)  |
| habilitado | booleano | No          | Estado habilitado de la NIC                    |

**Ejemplo**:

```json
{
  "machine": "54",
  "vnet": "3"
}
```

**Ejemplo de respuesta**:

```json
{
  "location": "/v4/machine_nics/78",
  "dbpath": "machine_nics/78",
  "$row": 78,
  "$key": "78"
}
```

{% hint style="info" %}
**Claves de red virtual**

El `vnet` El parámetro usa la clave/ID de la red. Por ejemplo, vnet "3" podría ser tu red externa. Puedes encontrar las claves de red enumerando las redes disponibles mediante el punto final de la API de redes.
{% endhint %}

## Ejemplo completo de creación de VM

Aquí tienes un flujo de trabajo completo para crear una VM con unidades, dispositivos e interfaces de red:

```bash
# Paso 1: Crear la VM
curl -X POST "https://your-vergeos.example.com/api/v4/vms" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "production-server",
    "description": "Servidor de aplicaciones de producción",
    "cluster": "1",
    "ram": 16384,
    "cpu_cores": 8,
    "guest_agent": "true",
    "video": "virtio",
    "uefi": "true"
  }'

# Respuesta: clave de VM = 42, clave de máquina = 54

# Paso 2: Agregar unidad de arranque
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "Unidad de arranque",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

# Paso 3: Agregar interfaz de red
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "vnet": "3"
  }'

# Paso 4: Agregar GPU (opcional)
curl -X POST "https://your-vergeos.example.com/api/v4/machine_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
    "settings_args": {}
  }'
```

{% hint style="info" %}
**Operaciones relacionadas**

* **Gestión de energía**: consulta [`Gestión de energía de la VM`](/knowledge-base/es/automation-api/vm-power-management.md) para iniciar/detener VMs
* **Configuración**: consulta [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md) para cambios de CPU/RAM
* **Operaciones avanzadas**: consulta [`Operaciones avanzadas de VM`](/knowledge-base/es/automation-api/vm-advanced-operations.md) para clonación y instantáneas
  {% endhint %}

{% hint style="info" %}
**¿Necesitas ayuda?**

Para obtener soporte adicional con la creación de VM:

* Consulta el portal de documentación de VergeOS
* Contacta con el soporte de VergeOS con mensajes de error específicos
* Revisa los registros del sistema para obtener información detallada del error
* Consulta los foros de la comunidad de VergeOS
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/knowledge-base/es/automation-api/vm-creation-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.