> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Venice API is OpenAI-compatible: use any OpenAI SDK with the base URL `https://api.venice.ai/api/v1` and a Venice API key, or pay per request from a USDC wallet through x402 with no account.
> Read model IDs from `GET /models` or `GET /models/traits` at runtime instead of hardcoding them from memory or from these pages. Models are added and retired often.
> Every model's price is in https://docs.venice.ai/pricing.md. Quote video and audio jobs with `POST /video/quote` or `POST /audio/quote` before you queue them.
> Search these docs from an MCP client at https://docs.venice.ai/mcp. The full agent guide is https://docs.venice.ai/agents.md.

# Decisiones tipadas con Jev

> Usa Jev para clasificar, puntuar y evaluar el estado de la aplicación con respuestas tipadas, probabilidades y confianza.

La mayoría de los modelos de lenguaje están diseñados para generar texto. Cuando una aplicación necesita una decisión, esto suele implicar pedirle JSON a un modelo, validar la respuesta y extraer el valor que controla el siguiente paso.

Jev es un modelo de decisión System One. En lugar de generar prosa, evalúa un `state` frente a preguntas con tipos de respuesta predefinidos y devuelve juicios listos para ser consumidos por máquinas.

> [!WARNING]
>
> Jev y la API de Decisiones están en beta. La disponibilidad y el comportamiento pueden cambiar sin previo aviso.

## Un ticket de soporte se convierte en una decisión

Supón que llega este mensaje:

> Mis pagos han fallado durante tres días y nadie ha respondido. Por favor, ayuden URGENTE.

Tu aplicación necesita saber a dónde enrutarlo, si es urgente y qué tan frustrado parece estar el cliente. Envía el mensaje una sola vez y haz las tres preguntas juntas:

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/decisions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Mis pagos han fallado durante tres días y nadie ha respondido. Por favor, ayuden URGENTE.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "¿Este mensaje requiere atención urgente?"
      },
      "department": {
        "type": "choice",
        "instructions": "¿Qué equipo debería gestionar este ticket?",
        "criteria": {
          "billing": "Pagos, facturas o reembolsos",
          "technical": "Errores, caídas o integraciones",
          "sales": "Precios, mejoras de plan o cuentas nuevas"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "¿Qué tan frustrado está el cliente?",
        "criteria": ["Tranquilo", "Frustrado", "Muy enojado"]
      }
    }
  }'
```

Jev devuelve una respuesta bajo cada ID de pregunta:

```json theme={"system"}
{
  "model": "jev-latest",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.95,
        "technical": 0.05,
        "sales": 0
      },
      "confidence": 0.93
    },
    "frustration": {
      "type": "score",
      "score": 1.27,
      "legend": {
        "0": "Tranquilo",
        "1": "Frustrado",
        "2": "Muy enojado"
      },
      "probabilities": {
        "0": 0,
        "1": 0.73,
        "2": 0.27
      },
      "confidence": 0.6
    }
  },
  "usage": {
    "input_tokens": 429,
    "output_tokens": 73
  }
}
```

Las probabilidades varían entre solicitudes. Evalúa Jev con ejemplos de tu propia aplicación antes de elegir umbrales para producción.

## Elige la forma de la respuesta

Jev admite tres tipos de preguntas:

| Tipo | Pregunta | Respuesta |
| - | - | - |
| `noul` | ¿Es cierta esta afirmación? | Una probabilidad de `0` (no) a `1` (sí) |
| `choice` | ¿Qué opción definida encaja mejor? | La opción seleccionada, la probabilidad de cada opción y la confianza |
| `score` | ¿Dónde se ubica esto en una rúbrica ordenada? | Una puntuación ponderada, leyenda de niveles, distribución de probabilidades y confianza |

### Noul: emite un juicio binario

Usa Noul cuando la probabilidad de sí sea directamente útil:

```json theme={"system"}
{
  "refund_requested": {
    "type": "noul",
    "instructions": "¿El cliente solicita explícitamente un reembolso?",
    "criteria": {
      "true": "El cliente pide que se le devuelva el dinero",
      "false": "El cliente no pide que se le devuelva el dinero"
    }
  }
}
```

Noul no tiene un campo `confidence` separado. Un valor cercano a `1` es un sí fuerte, cercano a `0` es un no fuerte, y cercano a `0.5` es incierto.

### Choice: enruta o clasifica

Usa Choice cuando la respuesta deba ser una entre un conjunto cerrado:

```json theme={"system"}
{
  "request_type": {
    "type": "choice",
    "instructions": "¿Cuál es la solicitud principal del cliente?",
    "criteria": {
      "refund": "Devolver dinero ya pagado",
      "troubleshooting": "Ayudar a resolver un problema del producto",
      "information": "Responder a una pregunta sin tomar acción",
      "other": null
    }
  }
}
```

Incluye una opción `other` o `none` cuando las opciones proporcionadas puedan no cubrir todos los estados.

### Score: mide un espectro

Usa Score cuando la respuesta se ubique en niveles ordenados:

```json theme={"system"}
{
  "severity": {
    "type": "score",
    "instructions": "¿Qué tan grave es el problema reportado?",
    "criteria": [
      "Cosmético o sin impacto material",
      "El flujo de trabajo está afectado pero existe una solución alternativa",
      "El flujo de trabajo crítico está bloqueado sin solución alternativa"
    ]
  }
}
```

Los índices de nivel comienzan en `0`. La puntuación devuelta está ponderada por probabilidad, por lo que puede caer entre dos niveles.

## Convierte la confianza en comportamiento de la aplicación

Las respuestas de Choice y Score incluyen tanto la distribución completa como un único valor de `confidence` derivado de ella. Esto permite que tu código trate la respuesta y la certeza como señales separadas:

```javascript theme={"system"}
const department = result.answers.department;

if (department.confidence >= 0.9) {
  await routeTicket(department.choice);
} else if (department.confidence >= 0.6) {
  await askForConfirmation(department.choice);
} else {
  await sendToHumanReview();
}
```

Usa umbrales más altos para acciones que sean costosas, destructivas, financieras o difíciles de revertir. La confianza no garantiza la exactitud; ayuda a tu aplicación a decidir cuándo no actuar automáticamente.

## Haz preguntas relacionadas en conjunto

Cada pregunta de una solicitud recibe el mismo state y se evalúa de forma independiente. Una respuesta de departamento no se convierte en contexto oculto para la pregunta sobre frustración.

Agrupa preguntas independientes cuando:

* Evalúan el mismo documento, registro, conversación o estado de la aplicación.
* Tu código pueda necesitar varias respuestas dependiendo del primer resultado.
* Quieras evitar enviar el mismo state en varias solicitudes.

Haz una segunda solicitud solo cuando su state u opciones disponibles dependan realmente de una respuesta anterior.

## Usa un state estructurado

`state` puede ser una cadena, un objeto JSON o un arreglo. Un state estructurado permite que las preguntas hagan referencia a registros específicos y a contexto de apoyo:

```json theme={"system"}
{
  "ticket": {
    "subject": "Cargo duplicado",
    "message": "Me cobraron dos veces. Por favor, reembolsen el duplicado."
  },
  "account": {
    "plan": "pro"
  },
  "refund_policy": "Los cargos duplicados califican para un reembolso."
}
```

Escribe instrucciones completas y nombra los campos relevantes, por ejemplo: “¿`ticket.message` solicita un reembolso cubierto por `refund_policy`?”

## Envía imágenes con una decisión

Usa el array opcional `images` cuando el juicio dependa de algo visual, como una captura de pantalla, un recibo o una foto de producto. Todas las preguntas de la solicitud pueden ver las mismas imágenes junto con `state`.

Cada entrada puede tener una de dos formas:

* Una cadena URI `data:`, por ejemplo `data:image/png;base64,iVBORw0KGgo...`
* Un objeto con `content_type` (`image/png`, `image/jpeg` o `image/jpg`) y `base64` (bytes en base64 sin el prefijo `data:`)

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/decisions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer reports that the checkout page shows an error after entering card details.",
    "images": [
      "data:image/png;base64,iVBORw0KGgo...",
      {
        "content_type": "image/jpeg",
        "base64": "/9j/4AAQSkZJRgABAQ..."
      }
    ],
    "questions": {
      "shows_error": {
        "type": "noul",
        "instructions": "Does the screenshot show a visible error message?"
      }
    }
  }'
```

Reglas de entrada de imágenes:

* Envía entre 1 y 4 imágenes por solicitud.
* Solo se aceptan PNG y JPEG.
* Cada entrada codificada puede tener como máximo 13.631.488 caracteres.
* Venice no descarga URL remotas. Incrusta los bytes de la imagen directamente.

## Descubre los modelos de decisión y sus límites

Venice ofrece dos modelos de decisión, ambos en beta:

| Modelo | ID | Privacidad |
| - | - | - |
| Jev (System One) | `jev-latest` | Anonimizada |
| Clef (System One) | `clef-api` | Privada |

Establece el campo `model` con el ID del modelo que quieras usar. Usa tu clave de API al listar los modelos de decisión, ya que la disponibilidad de modelos puede variar según la cuenta:

```bash cURL theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=decision" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

El modelo `jev-latest` admite actualmente:

* Hasta 32.000 tokens para `state` más la pregunta individual más larga
* Hasta 64.000 tokens para `state` más todas las preguntas combinadas
* Entrada de texto o JSON estructurado
* Privacidad anónima (`model_spec.privacy` es `anonymized`). Venice no envía tu identidad al proveedor. El proveedor puede ver el `state` y las preguntas que envías. Consulta [Privacidad](https://docs.venice.ai/es/overview/privacy.md).

El modelo `clef-api` admite actualmente:

* Hasta 32.768 tokens para `state` más la pregunta individual más larga
* Hasta 32.768 tokens para `state` más todas las preguntas combinadas
* Privacidad privada (`model_spec.privacy` es `private`). Consulta [Privacidad](https://docs.venice.ai/es/overview/privacy.md).

Considera la API de Modelos como fuente autoritativa, ya que los precios, límites y disponibilidad pueden cambiar.

## Cuándo usar otro modelo

Usa Jev para juicios acotados sobre los que tu software pueda actuar directamente. Usa un modelo de chat o de razonamiento cuando necesites:

* Prosa o explicaciones generadas
* Conversación de varios turnos
* Llamada de herramientas (tool calling)
* Respuestas abiertas
* Una larga cadena de razonamiento dependiente

## Próximos pasos

* [Referencia de la API `POST /decisions`](https://docs.venice.ai/es/api-reference/endpoint/decisions/create)
* [Referencia de compatibilidad TypeSafe `POST /systemone`](https://docs.venice.ai/es/api-reference/endpoint/decisions/systemone)
* [API List Models](https://docs.venice.ai/es/api-reference/endpoint/models/list.md)
* [Límites de tasa de la API](https://docs.venice.ai/es/api-reference/rate-limiting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.