Guías principales
Decisiones
Obtenga probabilidades, opciones y puntuaciones tipadas de un modelo de decisión
POST /v1/systemone evalúa un state frente a preguntas con nombre y devuelve una respuesta tipada por pregunta. La respuesta es JSON síncrono: una probabilidad, un nombre de opción o una puntuación que su código puede comparar y utilizar para bifurcar. No devuelve texto generado.
Decisiones o chat
| Use decisiones cuando | Use chat cuando |
|---|---|
| Su código necesita un número o una etiqueta sobre la cual actuar | Una persona u otro modelo lee la respuesta |
| Usted enruta, clasifica o filtra una solicitud: reembolso o no, qué equipo, qué tan urgente | Usted necesita explicaciones, resúmenes o borradores de texto |
| Usted hace varias preguntas fijas sobre la misma entrada en una sola llamada | Usted necesita herramientas, streaming, imágenes o mensajes de múltiples turnos |
El endpoint de decisión no acepta messages, tools, stream u otros controles de chat, y no está disponible en Batch. Mantenga su modelo de chat principal configurado por separado.
Elegir un modelo
curl "https://api.tokenlab.sh/v1/models?recommended_for=decision" \
-H "Authorization: Bearer sk-your-api-key"También puede filtrar con category=decision. Lea GET /v1/models/{model} para el modelo seleccionado antes de enviar solicitudes, y envíe el ID del modelo explícitamente. Los ejemplos en esta página utilizan jev-1.13.
Forma de la solicitud
| Campo | Tipo | Notas |
|---|---|---|
model | string | ID del modelo de decisión |
state | string, JSON object, or JSON array | La entrada a evaluar, como un ticket, una transcripción o un registro |
questions | object | Al menos una pregunta. Cada clave es el nombre de su pregunta; cada valor tiene type, instructions y criteria |
instructions y cada criterio también aceptan una cadena, un objeto JSON o una matriz JSON. La solicitud rechaza campos desconocidos.
type | criteria | Respuesta |
|---|---|---|
noul | Opcional. Un objeto con guía tanto para true como para false | noul: una probabilidad de 0 a 1 de que la afirmación sea verdadera |
choice | Requerido. Un objeto de 1 a 255 nombres de opciones, cada uno mapeado a una guía o null | choice: uno de los nombres de sus opciones. Puede incluir probabilities y confidence |
score | Requerido. Una matriz ordenada de 2 a 10 descripciones de nivel | score: un número de 0 al último índice de la matriz; puede ser fraccionario. Puede incluir legend, probabilities y confidence |
Evaluar un ticket
curl https://api.tokenlab.sh/v1/systemone \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-1.13",
"state": "I was charged twice. Please refund the duplicate payment.",
"questions": {
"refund_requested": {"type": "noul", "instructions": "Is a refund requested?"},
"department": {
"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"refunds": "Charges and refunds", "technical": "Software bugs"}
},
"urgency": {
"type": "score", "instructions": "Rate urgency",
"criteria": ["Routine enquiry", "Money affected", "Safety emergency"]
}
}
}'La respuesta mantiene los nombres de sus preguntas bajo answers. Los valores a continuación son ilustrativos:
{
"model": "jev-1.13",
"answers": {
"refund_requested": {"type": "noul", "noul": 0.97},
"department": {"type": "choice", "choice": "refunds"},
"urgency": {"type": "score", "score": 1}
},
"usage": {"input_tokens": 96, "output_tokens": 12}
}Usar las respuestas
- Cada pregunta obtiene una respuesta del mismo
type, bajo el mismo nombre. - Una respuesta
noules una probabilidad, no un booleano. Elija su propio umbral para cada acción. - Una respuesta
choicees siempre uno de los nombres de las opciones que envió. - Una respuesta
scoreindexa su matrizcriteria:1arriba significa "Money affected". - Pruebe las decisiones contra sus propios casos etiquetados antes de que impulsen reembolsos, escalaciones u otras acciones.
Usar desde MCP
El servidor MCP de TokenLab expone evaluate_decisions en los perfiles core y full. Llame primero a list_models con {"category":"decision"} y get_model, luego pase los mismos model, state y questions como argumentos de la herramienta. Lea structuredContent.answers y structuredContent.usage del resultado. La herramienta devuelve un resultado síncrono y no utiliza sondeo de tareas asíncronas.
Usar desde los SDKs
El SDK de JavaScript de TokenLab 0.1.2+ proporciona evaluateDecisions(body); el SDK de Python 0.1.2+ proporciona evaluate_decisions(body). El cuerpo es el mismo JSON que la solicitud HTTP. Ambos preservan las respuestas tipadas y el uso, y no reintentan automáticamente una solicitud fallida. Vea SDKs.
Costos y reintentos
- Las decisiones se cobran por tokens, a partir de
usage.input_tokensyusage.output_tokensen la respuesta, a los precios actuales de token del modelo. - Los precios pueden cambiar. Lea los detalles de precios del modelo o la API de precios en lugar de codificar un precio.
- Un modelo puede reportar tokens de salida incluso cuando su precio de salida es cero.
- Las solicitudes siguen su opción de entrega. Vea Facturación y precios.
- Un tiempo de espera (timeout) deja el resultado incierto. Verifique la solicitud en sus registros o en la Consola antes de enviar una solicitud pagada nuevamente.
Errores comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
400 en un campo como messages o stream | Los campos de chat no son parte de este endpoint | Envíe solo model, state y questions |
400 en criteria | Una choice tiene 0 o más de 255 opciones, un score tiene menos de 2 o más de 10 niveles, o un objeto noul carece de true o false | Corrija la definición de la pregunta |
| Las acciones se disparan con señales débiles | Una probabilidad noul fue tratada como verdadera o falsa | Compare contra un umbral que haya probado |
Referencia de la API
| Tema | Referencia |
|---|---|
| Evaluar decisiones | Evaluar decisiones |
| Listar modelos | Listar modelos |
| Precios | API de precios |
| Facturación y precios | Facturación y precios |