> 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/automate-protect-and-extend/es/ia-privada/open-ai-router.md).

# API compatible con OpenAI de VergeOS

## Descripción general

VergeOS proporciona un endpoint de API compatible con OpenAI que permite a las aplicaciones interactuar con modelos de lenguaje grandes (LLM) alojados localmente usando el formato estándar de la API de OpenAI. Esto le permite usar herramientas y bibliotecas conocidas mientras ejecuta modelos completamente dentro de su entorno VergeOS.

La API enruta automáticamente las solicitudes a sus asistentes configurados y a sus modelos subyacentes, proporcionando una interfaz unificada para las interacciones de IA.

## Requisitos previos

Antes de usar la API compatible con OpenAI, asegúrese de que los siguientes componentes estén en ejecución:

1. **AI-Helper Worker**: Este worker gestiona las solicitudes de la API y debe estar en ejecución. Se inicia automáticamente cuando el servicio de IA está habilitado.
2. **Al menos un asistente con un modelo en línea**: Se debe configurar un asistente y su modelo subyacente debe estar en estado "Online".

Para verificar estos requisitos previos:

1. Vaya a **AI → Ver workers** para confirmar que AI-Helper Worker está en ejecución
2. Vaya a **AI → Asistentes** para confirmar que al menos un asistente muestra el estado "Online"

## Puntos finales de la API

La API compatible con OpenAI está disponible en:

```
https://<your-vergeos-url>/v1
```

### Puntos finales compatibles

| Punto final            | Descripción                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `/v1/models`           | Lista los modelos disponibles (devuelve los asistentes configurados) |
| `/v1/chat/completions` | Generar completaciones de chat                                       |

## Autenticación

Las solicitudes de la API requieren autenticación mediante un token Bearer:

```
Authorization: Bearer <your-api-key>
```

### Creación de una clave API

1. Vaya a **Sistema → Usuarios**
2. Seleccione el usuario que será propietario de la clave API (o cree un usuario nuevo)
3. Haga clic en **Nueva clave API** en el menú de la izquierda
4. Configure los ajustes de la clave:
   * **Nombre**: Un nombre descriptivo para la clave (p. ej., `my-app-key`)
   * **Descripción** (opcional): Detalles adicionales sobre el propósito de la clave
   * **Tipo de vencimiento**: Elija "Establecer fecha" o "Nunca"
   * **Vence**: Si usa Establecer fecha, seleccione la fecha/hora de vencimiento
5. Guarde la clave y copie el token generado

{% hint style="warning" %}
**Seguridad**

La clave API solo se muestra una vez al crearse. Guárdela de forma segura, ya que no podrá recuperarse más tarde.
{% endhint %}

Las claves API heredan los permisos del usuario asociado. Para uso en producción, considere crear un usuario de API dedicado con los permisos adecuados.

## Uso básico

### Ejemplo en Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://your-vergeos-instance.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="qwen3-coder-14B",  # Usa el nombre del asistente
    messages=[
        {"role": "user", "content": "Escribe una función de hola mundo en Python"}
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)
```

### Ejemplo de cURL

```bash
curl https://your-vergeos-instance.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder-14B",
    "messages": [{"role": "user", "content": "¡Hola!"}],
    "max_tokens": 100
  }'
```

### Listar modelos disponibles

```bash
curl https://your-vergeos-instance.com/v1/models \
  -H "Authorization: Bearer your-api-key"
```

{% hint style="info" %}
**Nombres de modelos**

En las solicitudes de la API, use el **nombre del asistente** (p. ej., `qwen3-coder-14B`) como el `modelo` parámetro, no el nombre del modelo subyacente (p. ej., `Qwen3-14B-Q6_K`).
{% endhint %}

## Formato de respuesta

Las respuestas siguen el formato estándar de OpenAI con información adicional de temporización:

```json
{
  "id": "unique-completion-id",
  "object": "chat.completion",
  "created": 1768822431,
  "model": "assistant-name",
  "system_fingerprint": "assistant-name",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Contenido de la respuesta aquí"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 100,
    "total_tokens": 132
  },
  "timings": {
    "prompt_n": 12,
    "prompt_ms": 365.388,
    "prompt_per_token_ms": 30.449,
    "prompt_per_second": 32.84,
    "predicted_n": 100,
    "predicted_ms": 1620.788,
    "predicted_per_token_ms": 16.21,
    "predicted_per_second": 61.70
  }
}
```

La `timings` el campo proporciona métricas de rendimiento no disponibles en la API estándar de OpenAI.

## Configuración de asistentes

Los asistentes definen cómo interactúa la API con los modelos subyacentes. El asistente **Nombre** se usa como el `modelo` parámetro en las solicitudes de la API.

Para obtener instrucciones detalladas sobre cómo crear y configurar asistentes, consulte la [Guía de configuración de IA](/automate-protect-and-extend/es/ia-privada/configuration.md#ai-assistant-management).

{% hint style="success" %}
**Ajustes clave para el uso de la API**

* **Nombre**: Esto se convierte en el `modelo` parámetro en las llamadas a la API
* **Desactivar el razonamiento**: Habilítelo para que los modelos con capacidad de razonamiento devuelvan contenido mediante la API
* **Prompt del sistema**: Se aplica automáticamente a cada solicitud de la API
  {% endhint %}

## Workers

El sistema de IA usa dos tipos de workers:

* **AI-Helper Worker**: Procesa las solicitudes de la API y las enruta a los modelos. Se inicia automáticamente y es necesario para que la API funcione.
* **Workers de modelos**: Gestionan la inferencia de cada modelo en ejecución. Se crean automáticamente cuando un modelo se inicia.

Ver el estado del worker en **AI → Ver workers**.

## Conversaciones de varios turnos

La API admite conversaciones de varios turnos al incluir el historial de mensajes:

```python
response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "¿Qué es Python?"},
        {"role": "assistant", "content": "Python es un lenguaje de programación..."},
        {"role": "user", "content": "Muéstrame un ejemplo sencillo"}
    ]
)
```

Cuando **Historial de chat** está habilitado en el asistente, el sistema también puede mantener el contexto entre llamadas separadas a la API dentro de una sesión.

## Trabajar con modelos de razonamiento

Algunos modelos (como Qwen3) tienen capacidades de "razonamiento" en las que resuelven problemas internamente antes de responder.

Si está usando un modelo así mediante la API y recibe respuestas vacías, es posible que el modelo esté generando tokens de razonamiento que se filtran de la respuesta. Para obtener el contenido real de la respuesta:

1. Vaya a **AI → Asistentes**
2. Haga clic en su asistente
3. Haga clic en **Editar asistente**
4. Habilite el **Desactivar el razonamiento** interruptor
5. Haga clic en **Enviar**

Esto suprime el proceso de razonamiento y devuelve solo la respuesta final.

## Ejemplos de integración

### Integración en el IDE

Muchos IDE admiten endpoints personalizados compatibles con OpenAI. Configure su IDE con:

* **URL base de la API**: `https://your-vergeos-instance.com/v1`
* **Clave API**: Su clave API de VergeOS
* **Modelo**: El nombre de su asistente (p. ej., `qwen3-coder-14B`)

### Integración de aplicaciones

Use cualquier biblioteca cliente de OpenAI:

{% tabs %}
{% tab title="Python" %}

```python
from openai import OpenAI
client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key")
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://your-vergeos-instance.com/v1',
  apiKey: 'your-key'
});
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl https://your-vergeos-instance.com/v1/chat/completions \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "assistant-name", "messages": [...]}'
```

{% endtab %}
{% endtabs %}

## Solución de problemas

### Error de inicio de sesión requerido

```json
{"err":"Se requiere inicio de sesión"}
```

**Causa**: Falta la clave API o no es válida.

**Solución**: Incluya una clave API válida en el encabezado Authorization.

### Contenido de respuesta vacío

**Causa**: El modelo está usando tokens de razonamiento que se filtran de la salida.

**Solución**: Habilite "Desactivar el razonamiento" en la configuración del asistente.

### Modelo no encontrado

**Causa**: El nombre de modelo especificado no coincide con ningún asistente.

**Solución**:

* Use el nombre exacto del asistente (sensible a mayúsculas y minúsculas)
* Verifique que el asistente exista en **AI → Asistentes**
* Asegúrese de que el modelo del asistente esté en línea

### Conexión rechazada

**Causa**: AI-Helper Worker no está en ejecución.

**Solución**:

* Compruebe **AI → Ver workers** para verificar el estado de AI-Helper Worker
* Reinicie el servicio de IA si es necesario

### Respuestas lentas

**Causa**: El modelo se está cargando o está muy cargado.

**Solución**:

* Compruebe el uso de recursos del worker en **AI → Ver workers**
* Considere asignar más núcleos de CPU o RAM al modelo
* Use un modelo más pequeño para obtener respuestas más rápidas

***

**Compatibilidad de versiones**: Esta funcionalidad está disponible en VergeOS 26.0 y versiones posteriores.


---

# 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/automate-protect-and-extend/es/ia-privada/open-ai-router.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.