# API REST de DMR


Una vez habilitado Model Runner, nuevos endpoints de la API estarán disponibles. Puedes usar estos endpoints para interactuar con un modelo de forma programática. Docker Model Runner proporciona compatibilidad con los formatos de API de OpenAI, Anthropic y Ollama.

## Determinar la URL base

La URL base para interactuar con los endpoints depende de cómo ejecutes Docker y de qué formato de API estés utilizando.

**Docker Desktop**



| Acceso desde            | URL base                              |
| ----------------------- | ------------------------------------- |
| Contenedores            | `http://model-runner.docker.internal` |
| Procesos del host (TCP) | `http://localhost:12434`              |

> [!NOTE]
> El acceso TCP desde el host debe estar habilitado. Consulta [Habilitar Docker Model Runner](/ai/model-runner/api-reference/get-started/#enable-docker-model-runner-in-docker-desktop).

**Docker Engine**



| Acceso desde      | URL base                  |
| ----------------- | ------------------------- |
| Contenedores      | `http://172.17.0.1:12434` |
| Procesos del host | `http://localhost:12434`  |

> [!NOTE]
> Es posible que la interfaz `172.17.0.1` no esté disponible por defecto para los contenedores dentro de un proyecto de Compose.
> En este caso, añade una directiva `extra_hosts` al YAML de tu servicio de Compose:
>
> ```yaml
> extra_hosts:
>   - "model-runner.docker.internal:host-gateway"
> ```
>
> De este modo, podrás acceder a las API de Docker Model Runner en `http://model-runner.docker.internal:12434/`



### URL base para herramientas de terceros

Al configurar herramientas de terceros que esperan API compatibles con OpenAI, utiliza estas URL base:

| Tipo de herramienta             | Formato de URL base                 |
| ------------------------------- | ----------------------------------- |
| SDK / clientes de OpenAI        | `http://localhost:12434/engines/v1` |
| SDK / clientes de Anthropic     | `http://localhost:12434`            |
| Clientes compatibles con Ollama | `http://localhost:12434`            |

Consulta [Integraciones de IDE y herramientas](/ai/model-runner/api-reference/ide-integrations/) para ver ejemplos de configuración específicos.

## API compatibles

Docker Model Runner admite múltiples formatos de API:

| API                                                              | Descripción                                             | Caso de uso                                         |
| ---------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------- |
| [API de OpenAI](#openai-compatible-api)                          | Completados de chat y embeddings compatibles con OpenAI | La mayoría de frameworks y herramientas de IA       |
| [API de Anthropic](#anthropic-compatible-api)                    | Endpoint de mensajes compatible con Anthropic           | Herramientas creadas para Claude                    |
| [API de Ollama](#ollama-compatible-api)                          | Endpoints compatibles con Ollama                        | Herramientas creadas para Ollama                    |
| [API de generación de imágenes](#image-generation-api-diffusers) | Generación de imágenes basada en Diffusers              | Generación de imágenes a partir de prompts de texto |
| [API de DMR](#dmr-native-endpoints)                              | Endpoints nativos de Docker Model Runner                | Gestión de modelos                                  |

## API compatible con OpenAI

DMR implementa la especificación de la API de OpenAI para lograr la máxima compatibilidad con las herramientas y frameworks existentes.

### Endpoints

| Endpoint                                | Método | Descripción                                                                            |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------- |
| `/engines/v1/models`                    | GET    | [Listar modelos](https://platform.openai.com/docs/api-reference/models/list)           |
| `/engines/v1/models/{namespace}/{name}` | GET    | [Obtener modelo](https://platform.openai.com/docs/api-reference/models/retrieve)       |
| `/engines/v1/chat/completions`          | POST   | [Crear completado de chat](https://platform.openai.com/docs/api-reference/chat/create) |
| `/engines/v1/completions`               | POST   | [Crear completado](https://platform.openai.com/docs/api-reference/completions/create)  |
| `/engines/v1/embeddings`                | POST   | [Crear embeddings](https://platform.openai.com/docs/api-reference/embeddings/create)   |

> [!NOTE]
> Opcionalmente, puedes incluir el nombre del motor en la ruta: `/engines/llama.cpp/v1/chat/completions`.
> Esto es útil cuando se ejecutan varios motores de inferencia.

### Formato del nombre del modelo

Al especificar un modelo en las solicitudes de la API, utiliza el identificador de modelo completo, incluyendo el espacio de nombres:

```json
{
  "model": "ai/smollm2",
  "messages": [...]
}
```

Formatos comunes de nombres de modelos:

- Modelos de Docker Hub: `ai/smollm2`, `ai/llama3.2`, `ai/qwen2.5-coder`
- Versiones con etiquetas: `ai/smollm2:360M-Q4_K_M`
- Modelos personalizados: `miorg/mimodel`

### Parámetros admitidos

Se admiten los siguientes parámetros de la API de OpenAI:

| Parámetro           | Tipo         | Descripción                                                          |
| ------------------- | ------------ | -------------------------------------------------------------------- |
| `model`             | string       | Requerido. El identificador del modelo.                              |
| `messages`          | array        | Requerido para completados de chat. El historial de la conversación. |
| `prompt`            | string       | Requerido para completados. El texto del prompt.                     |
| `max_tokens`        | integer      | Cantidad máxima de tokens a generar.                                 |
| `temperature`       | float        | Temperatura de muestreo (0.0-2.0).                                   |
| `top_p`             | float        | Parámetro de muestreo nucleus (0.0-1.0).                             |
| `stream`            | Boolean      | Habilitar respuestas en streaming.                                   |
| `stop`              | string/array | Secuencias de parada.                                                |
| `presence_penalty`  | float        | Penalización de presencia (-2.0 a 2.0).                              |
| `frequency_penalty` | float        | Penalización de frecuencia (-2.0 a 2.0).                             |

### Limitaciones y diferencias con OpenAI

Ten en cuenta estas diferencias al utilizar la API compatible con OpenAI de DMR:

| Característica      | Comportamiento de DMR                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------- |
| Clave de API        | No requerida. DMR ignora la cabecera `Authorization`.                                    |
| Llamada a funciones | Admitida con llama.cpp para modelos compatibles.                                         |
| Visión              | Admitida para modelos multimodales (por ejemplo, LLaVA).                                 |
| Modo JSON           | Admitido mediante `response_format: {"type": "json_object"}`.                            |
| Logprobs            | Admitido.                                                                                |
| Conteo de tokens    | Utiliza el codificador de tokens nativo del modelo, el cual puede diferir del de OpenAI. |

## API compatible con Anthropic

DMR proporciona compatibilidad con la [API de mensajes de Anthropic](https://platform.claude.com/docs/en/api/messages) para herramientas y frameworks creados para Claude.

### Endpoints

| Endpoint                              | Método | Descripción                                                                 |
| ------------------------------------- | ------ | --------------------------------------------------------------------------- |
| `/anthropic/v1/messages`              | POST   | [Crear un mensaje](https://platform.claude.com/docs/en/api/messages/create) |
| `/anthropic/v1/messages/count_tokens` | POST   | [Contar tokens](https://docs.anthropic.com/en/api/messages-count-tokens)    |

### Parámetros admitidos

Se admiten los siguientes parámetros de la API de Anthropic:

| Parámetro        | Tipo    | Descripción                                 |
| ---------------- | ------- | ------------------------------------------- |
| `model`          | string  | Requerido. El identificador del modelo.     |
| `messages`       | array   | Requerido. Los mensajes de la conversación. |
| `max_tokens`     | integer | Cantidad máxima de tokens a generar.        |
| `temperature`    | float   | Temperatura de muestreo (0.0-1.0).          |
| `top_p`          | float   | Parámetro de muestreo nucleus.              |
| `top_k`          | integer | Parámetro de muestreo top-k.                |
| `stream`         | Boolean | Habilitar respuestas en streaming.          |
| `stop_sequences` | array   | Secuencias de parada personalizadas.        |
| `system`         | string  | Prompt del sistema.                         |

### Ejemplo: Chat con la API de Anthropic

```bash
curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### Ejemplo: Respuesta en streaming

```bash
curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 10"}
    ]
  }'
```

## API compatible con Ollama

DMR también proporciona endpoints compatibles con Ollama para herramientas y frameworks creados para Ollama.

### Endpoints

| Endpoint          | Método | Descripción                    |
| ----------------- | ------ | ------------------------------ |
| `/api/tags`       | GET    | Listar modelos disponibles     |
| `/api/show`       | POST   | Mostrar información del modelo |
| `/api/chat`       | POST   | Crear completado de chat       |
| `/api/generate`   | POST   | Crear completado               |
| `/api/embeddings` | POST   | Generar embeddings             |

### Ejemplo: Chat con la API de Ollama

```bash
curl http://localhost:12434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### Ejemplo: Listar modelos

```bash
curl http://localhost:12434/api/tags
```

## API de generación de imágenes (Diffusers)

DMR admite la generación de imágenes a través del backend de Diffusers, lo que te permite generar imágenes a partir de prompts de texto utilizando modelos como Stable Diffusion.

> [!NOTE]
> El backend de Diffusers requiere una GPU NVIDIA con soporte para CUDA y solo está disponible en Linux (x86_64 y ARM64). Consulta [Motores de inferencia](/ai/model-runner/api-reference/inference-engines/#diffusers) para obtener instrucciones de configuración.

### Endpoint

| Endpoint                                   | Método | Descripción                                       |
| ------------------------------------------ | ------ | ------------------------------------------------- |
| `/engines/diffusers/v1/images/generations` | POST   | Generar una imagen a partir de un prompt de texto |

### Parámetros admitidos

| Parámetro | Tipo   | Descripción                                                                    |
| --------- | ------ | ------------------------------------------------------------------------------ |
| `model`   | string | Requerido. El identificador del modelo (por ejemplo, `stable-diffusion:Q4`).   |
| `prompt`  | string | Requerido. La descripción en texto de la imagen a generar.                     |
| `size`    | string | Dimensiones de la imagen en formato `ANCHO_POR_ALTO` (por ejemplo, `512x512`). |

### Formato de respuesta

El API devuelve una respuesta JSON con la imagen generada codificada en base64:

```json
{
  "data": [
    {
      "b64_json": "<base64-encoded-image-data>"
    }
  ]
}
```

### Ejemplo: Generar una imagen

```bash
curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png
```

Este comando:

1. Envía una solicitud POST al endpoint de generación de imágenes de Diffusers.
2. Especifica el modelo, el prompt y el tamaño de la imagen de salida.
3. Extrae la imagen codificada en base64 de la respuesta utilizando `jq`.
4. Decodifica los datos en base64 y los guarda como `image.png`.

## Endpoints nativos de DMR

Estos endpoints son específicos de Docker Model Runner para la gestión de modelos:

| Endpoint                     | Método | Descripción                 |
| ---------------------------- | ------ | --------------------------- |
| `/models/create`             | POST   | Descargar/crear un modelo   |
| `/models`                    | GET    | Listar modelos locales      |
| `/models/{namespace}/{name}` | GET    | Obtener detalles del modelo |
| `/models/{namespace}/{name}` | DELETE | Eliminar un modelo local    |

## Ejemplos de API REST

### Solicitud desde el interior de un contenedor

Para llamar al endpoint de OpenAI `chat/completions` desde el interior de otro contenedor utilizando `curl`:

```bash
#!/bin/sh

curl http://model-runner.docker.internal/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'

```

### Solicitud desde el host utilizando TCP

Para llamar al endpoint de OpenAI `chat/completions` desde el host a través de TCP:

1. Habilita el soporte de TCP en el lado del host desde la interfaz de usuario de Docker Desktop, o a través de la [CLI de Docker Desktop](/desktop/features/desktop-cli/).
   Por ejemplo: `docker desktop enable model-runner --tcp <port>`.

   Si estás ejecutando en Windows, habilita también la inferencia respaldada por GPU.
   Consulta [Habilitar Docker Model Runner](/ai/model-runner/api-reference/get-started/#enable-docker-model-runner-in-docker-desktop).

2. Interactúa con él como se documenta en la sección anterior utilizando `localhost` y el puerto correcto.

```bash
#!/bin/sh

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant."
          },
          {
              "role": "user",
              "content": "Please write 500 words about the fall of Rome."
          }
      ]
  }'
```

### Solicitud desde el host utilizando un socket Unix

Para llamar al endpoint de OpenAI `chat/completions` a través del socket de Docker desde el host utilizando `curl`:

```bash
#!/bin/sh

curl --unix-socket $HOME/.docker/run/docker.sock \
    localhost/exp/vDD4.40/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'
```

### Respuestas en streaming

Para recibir respuestas en streaming, establece `stream: true`:

```bash
curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "stream": true,
      "messages": [
          {"role": "user", "content": "Count from 1 to 10"}
      ]
  }'
```

## Uso con SDK de OpenAI

### Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed"  # DMR no requiere una clave de API
)

response = client.chat.completions.create(
    model="ai/smollm2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

### Node.js

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:12434/engines/v1",
  apiKey: "not-needed",
});

const response = await client.chat.completions.create({
  model: "ai/smollm2",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
```

## Qué sigue

- [Integraciones de IDE y herramientas](/ai/model-runner/api-reference/ide-integrations/) - Configura Cline, Continue, Cursor y otras herramientas
- [Opciones de configuración](/ai/model-runner/api-reference/configuration/) - Ajusta el tamaño del contexto y los parámetros de tiempo de ejecución
- [Motores de inferencia](/ai/model-runner/api-reference/inference-engines/) - Obtén información sobre las opciones de llama.cpp, vLLM y Diffusers