Cinco ejemplos que puedes ejecutar tal cual

Peticiones completas —un estado, preguntas tipadas y un comando— para cinco tareas que un modelo de decisión hace bien. La suite de pruebas envía cada cuerpo de esta página al handler real, así que ninguno puede dejar de funcionar en silencio.

Qué es reproducible aquí

Cada cuerpo de esta página es exactamente el que la suite de pruebas envía a POST /api/v1/decisions, con solo el proveedor del modelo simulado. Si un campo cambia de nombre, una etiqueta se rechaza o un límite baja, la prueba falla antes de que esta página pueda publicar una petición que ya no funciona.

Lo que se repite es la petición y los invariantes de la respuesta: cada etiqueta declarada aparece en probabilities, cada distribución suma 1, la respuesta nombra el modelo que contestó y la llamada lleva un requestId. Lo que no se repite es el número: la distribución sale de los pesos y puede moverse cuando el modelo cambia. Una ejecución es una observación, no un benchmark.

Se muestran los dos contratos allí donde difieren. POST /api/v1/decisions necesita clave de API y acepta preguntas choice, noul y score. POST /api/decide no necesita clave y solo acepta preguntas choice, así que su cuerpo de abajo deja fuera las demás y las nombra en lugar de ocultarlas.

¿Todavía sin clave? Cada cuerpo sin clave de abajo funciona ahora mismo desde una terminal, contado contra la cuota gratuita de la sesión de navegador que nombra. Una clave de pago sube la cuota diaria, eleva el límite del estado de 8.000 caracteres a la ventana del modelo y añade las preguntas noul y score.

Ticket de soporte: cola y urgencia

Un mensaje, dos preguntas: qué cola es responsable del ticket y con qué rapidez tiene que verlo una persona.

El enrutamiento y el triaje suelen ser dos sistemas alimentados por dos modelos, o por una lista de palabras clave que se queda obsoleta. Aquí son dos preguntas sobre el mismo estado en una sola llamada: cuestan una decisión y no pueden discrepar sobre lo que dice el mensaje. La cola es una elección entre cuatro etiquetas; la urgencia es una puntuación sobre cuatro niveles ordenados, que devuelve un número y una distribución en lugar de un cajón elegido de antemano.

El cuerpo sin clave solo lleva las preguntas de tipo choice; urgency necesita el endpoint con clave.

POST /api/v1/decisions · con tu clave de API

curl --fail-with-body https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $CLEF_FLASH_KEY" \
  --data-binary @- <<'CLEF_REQUEST'
{
  "text": "Nadia wrote: I was charged twice for the October invoice — $38 on 2 October and $38 again on 3 October. I emailed support on Monday and got no reply. This is the second month in a row I have had to chase this, and I am close to cancelling.",
  "questions": [
    {
      "id": "queue",
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "a charge, an invoice, a refund or a plan change",
        "technical": "a bug or an error message",
        "account": "login, access or profile details",
        "cancellation": "they want to stop paying"
      }
    },
    {
      "id": "urgency",
      "type": "score",
      "instructions": "How quickly does this need a human?",
      "criteria": [
        "whenever",
        "this week",
        "today",
        "immediately"
      ]
    }
  ]
}
CLEF_REQUEST

POST /api/decide · sin clave

curl --fail-with-body https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": "Nadia wrote: I was charged twice for the October invoice — $38 on 2 October and $38 again on 3 October. I emailed support on Monday and got no reply. This is the second month in a row I have had to chase this, and I am close to cancelling.",
  "questions": [
    {
      "id": "queue",
      "prompt": "Which queue should own this ticket?",
      "options": [
        "billing",
        "technical",
        "account",
        "cancellation"
      ]
    }
  ],
  "sessionId": "example-support-triage"
}
CLEF_REQUEST

Qué debe contener una respuesta correcta

  • answers.queue.probabilities contiene exactamente las cuatro etiquetas declaradas y suma 1.
  • answers.urgency.score es un número entre 0 y 3, y needsReview es verdadero cuando su confianza queda por debajo del umbral de 0,85.
  • Una sola llamada respondió las dos preguntas, así que cuestan una decisión de la cuota diaria.

Comentario: decisión de moderación y su categoría

Una pregunta noul plantea un sí/no como probabilidad; una pregunta choice nombra el área de la política. Ninguna entrega un veredicto que haya que creer sin más.

La moderación es una decisión de umbral, no una clasificación. noul te da P(el comentario incumple la norma), así que el umbral sigue siendo tuyo: eliminar automáticamente por encima de 0,95, encolar para una persona entre 0,5 y 0,95, publicar por debajo de 0,5. La segunda pregunta solo importa cuando alguien va a revisarlo de todos modos, y le ahorra leer el hilo para deducir por qué se retuvo el comentario.

El cuerpo sin clave solo lleva las preguntas de tipo choice; violates necesita el endpoint con clave.

POST /api/v1/decisions · con tu clave de API

curl --fail-with-body https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $CLEF_FLASH_KEY" \
  --data-binary @- <<'CLEF_REQUEST'
{
  "text": "Comment on the release thread: 'Been using this for a year and it is fine, but whoever runs your support account is a joke and should be fired.'",
  "questions": [
    {
      "id": "violates",
      "type": "noul",
      "instructions": "Does this comment break the rule against personal attacks?",
      "criteria": {
        "true": "it attacks a person rather than the product or the service",
        "false": "it criticises the product or the service without attacking a person"
      }
    },
    {
      "id": "category",
      "type": "choice",
      "instructions": "Which rule does the comment touch?",
      "criteria": {
        "harassment": "personal abuse aimed at a person",
        "spam": "advertising, links or repetition",
        "off_topic": "nothing to do with the discussion",
        "none": "within the rules"
      }
    }
  ]
}
CLEF_REQUEST

POST /api/decide · sin clave

curl --fail-with-body https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": "Comment on the release thread: 'Been using this for a year and it is fine, but whoever runs your support account is a joke and should be fired.'",
  "questions": [
    {
      "id": "category",
      "prompt": "Which rule does the comment touch?",
      "options": [
        "harassment",
        "spam",
        "off_topic",
        "none"
      ]
    }
  ],
  "sessionId": "example-comment-moderation"
}
CLEF_REQUEST

Qué debe contener una respuesta correcta

  • answers.violates.noul es una probabilidad entre 0 y 1: compárala con tu propio umbral, no es un veredicto.
  • answers.violates.needsReview es verdadero cuando ningún lado de la pregunta obtiene una mayoría clara.
  • answers.category.probabilities contiene exactamente las cuatro categorías declaradas y suma 1.

Consulta entrante: intención y señal de compra

Dos preguntas baratas que deciden si una persona responde hoy o la consulta espera en la cola.

La intención por sí sola no distingue a un comprador de alguien que pide soporte gratuito, y un filtro de palabras clave tampoco. Combinar una pregunta choice sobre la intención con una noul sobre el presupuesto convierte dos señales débiles en una regla de enrutamiento defendible: intención alta y P(presupuesto) por encima de 0,8 va a ventas hoy; intención alta con probabilidad baja pasa a la secuencia de bienvenida; la intención baja va a soporte.

El cuerpo sin clave solo lleva las preguntas de tipo choice; budget necesita el endpoint con clave.

POST /api/v1/decisions · con tu clave de API

curl --fail-with-body https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $CLEF_FLASH_KEY" \
  --data-binary @- <<'CLEF_REQUEST'
{
  "text": "Contact form: 'Hi — we are a 40-person logistics company in Rotterdam. We are evaluating decision models for our support queue and would need roughly 30,000 calls a month. I have budget approved for this quarter and can sign off; can we get a call this week?'",
  "questions": [
    {
      "id": "intent",
      "type": "choice",
      "instructions": "What is this sender trying to do?",
      "criteria": {
        "buying": "evaluating or asking to purchase",
        "support": "asking for help with something they already use",
        "partnership": "proposing a commercial arrangement of their own",
        "spam": "no genuine enquiry behind the message"
      }
    },
    {
      "id": "budget",
      "type": "noul",
      "instructions": "Does the sender name a budget, an approval or a purchase process?",
      "criteria": {
        "true": "they mention money set aside, an approved spend or a sign-off they can give",
        "false": "they ask about price or features without naming any authority to buy"
      }
    }
  ]
}
CLEF_REQUEST

POST /api/decide · sin clave

curl --fail-with-body https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": "Contact form: 'Hi — we are a 40-person logistics company in Rotterdam. We are evaluating decision models for our support queue and would need roughly 30,000 calls a month. I have budget approved for this quarter and can sign off; can we get a call this week?'",
  "questions": [
    {
      "id": "intent",
      "prompt": "What is this sender trying to do?",
      "options": [
        "buying",
        "support",
        "partnership",
        "spam"
      ]
    }
  ],
  "sessionId": "example-lead-qualification"
}
CLEF_REQUEST

Qué debe contener una respuesta correcta

  • answers.intent.probabilities nombra las cuatro etiquetas y suma 1.
  • answers.budget.noul es la probabilidad de que quien escribe pueda aprobar una compra, en su propia escala: no es una parte de la pregunta de intención.
  • Una consulta de spam puntúa bajo en las dos preguntas, y de eso depende la regla de enrutamiento.

Transacción en JSON: categoría contable y marca de revisión

Un estado puede ser un objeto JSON. Aquí los campos son la prueba y las preguntas son las dos decisiones que tiene que tomar el libro contable.

Una cadena de JSON escapado es la forma que peor lee un modelo, así que el endpoint envía un objeto como objeto. La categorización es una elección entre las cuentas del libro; la revisión es una puntuación sobre tres niveles ordenados, lo que permite al equipo contable fijar dónde está la línea en lugar de aceptar un sí/no de un clasificador.

El cuerpo sin clave solo lleva las preguntas de tipo choice; review necesita el endpoint con clave.

POST /api/v1/decisions · con tu clave de API

curl --fail-with-body https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $CLEF_FLASH_KEY" \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": {
    "merchant": "Uber",
    "description": "Ride to client office after the workshop",
    "amount": 48.2,
    "currency": "USD",
    "occurred_on": "2026-11-04",
    "card": "corporate",
    "submitted_by": "a.reyes"
  },
  "questions": [
    {
      "id": "category",
      "type": "choice",
      "instructions": "Which ledger account does this expense belong to?",
      "criteria": {
        "travel": "transport to or between work locations",
        "meals": "food and drink",
        "software": "subscriptions and licences",
        "hardware": "equipment",
        "other": "none of the above"
      }
    },
    {
      "id": "review",
      "type": "score",
      "instructions": "How much human review does this expense need?",
      "criteria": [
        "post automatically",
        "check the receipt",
        "hold for approval"
      ]
    }
  ]
}
CLEF_REQUEST

POST /api/decide · sin clave

curl --fail-with-body https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": {
    "merchant": "Uber",
    "description": "Ride to client office after the workshop",
    "amount": 48.2,
    "currency": "USD",
    "occurred_on": "2026-11-04",
    "card": "corporate",
    "submitted_by": "a.reyes"
  },
  "questions": [
    {
      "id": "category",
      "prompt": "Which ledger account does this expense belong to?",
      "options": [
        "travel",
        "meals",
        "software",
        "hardware",
        "other"
      ]
    }
  ],
  "sessionId": "example-expense-category"
}
CLEF_REQUEST

Qué debe contener una respuesta correcta

  • El objeto JSON viaja como objeto: lo lleva state, y el modelo lee campos en lugar de texto escapado.
  • answers.category.probabilities enumera las cinco cuentas del libro y suma 1.
  • answers.review.score va de 0 (contabilizar automáticamente) a 2 (retener para aprobación).

Informe de error: componente y gravedad

Las dos preguntas son de tipo choice, así que este ejemplo funciona de principio a fin sin clave de API.

Un turno de guardia necesita una alerta, no un párrafo de prosa generada. Dos preguntas de tipo choice sobre el mismo informe nombran el componente responsable del fallo y con cuánta urgencia despertar a alguien; y como ambas son choices, el contrato gratuito /api/decide puede ejecutarlo entero, que es la forma más rápida de comprobar si el modelo coincide con tu criterio en incidentes reales antes de conectarlo.

POST /api/v1/decisions · con tu clave de API

curl --fail-with-body https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $CLEF_FLASH_KEY" \
  --data-binary @- <<'CLEF_REQUEST'
{
  "text": "Checkout failed for three customers in ten minutes.\nTypeError: Cannot read properties of undefined (reading 'amount')\n  at createPaymentIntent (billing/checkout.ts:142:31)\n  at handlePost (app/api/checkout/route.ts:88:12)\nUpstream returned 402 for card_declined, then the handler threw before the refund branch ran.\nOnly the EUR flow is affected; USD checkouts completed.",
  "questions": [
    {
      "id": "component",
      "type": "choice",
      "instructions": "Which component owns this failure?",
      "criteria": {
        "api": "request handling, validation or routing",
        "billing": "payments, invoices or credits",
        "ui": "rendering or client-side behaviour",
        "auth": "login, sessions or permissions"
      }
    },
    {
      "id": "severity",
      "type": "choice",
      "instructions": "How severe is this incident?",
      "criteria": {
        "low": "cosmetic or internal only",
        "medium": "degraded for some users, workaround exists",
        "high": "customers cannot complete a purchase",
        "critical": "data loss, security exposure or full outage"
      }
    }
  ]
}
CLEF_REQUEST

POST /api/decide · sin clave

curl --fail-with-body https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  --data-binary @- <<'CLEF_REQUEST'
{
  "state": "Checkout failed for three customers in ten minutes.\nTypeError: Cannot read properties of undefined (reading 'amount')\n  at createPaymentIntent (billing/checkout.ts:142:31)\n  at handlePost (app/api/checkout/route.ts:88:12)\nUpstream returned 402 for card_declined, then the handler threw before the refund branch ran.\nOnly the EUR flow is affected; USD checkouts completed.",
  "questions": [
    {
      "id": "component",
      "prompt": "Which component owns this failure?",
      "options": [
        "api",
        "billing",
        "ui",
        "auth"
      ]
    },
    {
      "id": "severity",
      "prompt": "How severe is this incident?",
      "options": [
        "low",
        "medium",
        "high",
        "critical"
      ]
    }
  ],
  "sessionId": "example-incident-triage"
}
CLEF_REQUEST

Qué debe contener una respuesta correcta

  • Vuelven answers.component y answers.severity, cada una con sus cuatro etiquetas en probabilities.
  • Las dos preguntas son de tipo choice, así que el cuerpo sin clave de abajo lleva la petición completa: no se omite nada.
  • El needsReview de nivel superior es verdadero cuando alguna respuesta queda por debajo del umbral, que es la señal para avisar a una persona en lugar del guardia.

Adaptar uno de estos ejemplos

Sustituye el estado por tu propio texto, o por un objeto JSON, y conserva las preguntas. El esquema es la parte que exige pensar: una pregunta choice necesita entre 2 y 12 etiquetas con una línea de guía cada una, una noul necesita exactamente true y false, y una score necesita entre 2 y 7 niveles ordenados de peor a mejor. La guía es lo que lee el modelo cuando las etiquetas por sí solas son ambiguas, así que merece la pena escribirla con cuidado.

Las preguntas se agrupan, no se acumulan: una petición puede llevar hasta 8 preguntas sobre el mismo estado y sigue costando una decisión. Dos estados distintos son dos peticiones. Sin clave el estado está limitado a 8.000 caracteres y el cuerpo a 64 KB; una clave de pago acepta 8 MB y el límite del estado pasa a ser la ventana del modelo que nombres.

  • El umbral por defecto es 0,85. Una respuesta por debajo vuelve con needsReview: true, y el umbral es tuyo: se mueve entre 0,5 y 1.
  • Nombra un modelo para fijar la respuesta a unos pesos concretos; omite model para usar el modelo por defecto de este despliegue. La respuesta siempre dice qué modelo contestó.
  • Ramifica según code, nunca según la frase del error. La lista completa está en /docs.
Clef-Flash playground community-hosted

Community-hosted demo of the 9B model. Runs live in your browser session.

Preguntas frecuentes

¿Puedo ejecutarlos sin clave de API?

Sí, mientras todas las preguntas sean de tipo choice. Cada ejemplo muestra un cuerpo sin clave para /api/decide; esos se cuentan contra la cuota gratuita de la sesión de navegador que nombra el cuerpo. Los dos ejemplos con una pregunta noul o score muestran también el cuerpo con clave, porque ese contrato es el que las lleva.

¿Por qué mis probabilidades diferirán de las de otra ejecución?

Porque son los números del modelo, no una tabla fija. Los pesos y el estado determinan la distribución, y una actualización del modelo puede moverla. Lo que permanece es la forma: cada etiqueta declarada aparece, la distribución suma 1 y la respuesta nombra el modelo y la petición.

¿Estos ejemplos se quedan obsoletos?

Viven en el repositorio junto al código y la suite de pruebas los envía al endpoint en cada ejecución. Si uno deja de aceptarse, la prueba falla y la página no se publica con él. Los cuerpos de esta página no pueden separarse del contrato sin romper la compilación.

¿Cuántas decisiones cuesta uno de estos ejemplos?

Una, lleve las preguntas que lleve, hasta 8 por petición. La cuota diaria cuenta llamadas, no preguntas; el tiempo de modelo lo mide el límite de crédito aparte, y crece con la longitud del estado.

¿Necesitas más cuota?

Los planes de pago amplían el límite diario y emiten una clave de API. Consulta la página de precios o escríbenos para volúmenes altos.