Documentación de la API de decisión

El endpoint

POST https://clef-flash.com/api/decide con un cuerpo JSON. De forma opcional, autentícate con una clave de API para aumentar la cuota diaria. El nivel gratuito funciona sin clave y se cuenta por sesión de navegador.

curl -X POST https://clef-flash.com/api/decide \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer cfl_live_xxx' \
  -d '{
    "state": "Customer wrote: I was charged twice for the October invoice.",
    "questions": [
      {
        "id": "intent",
        "prompt": "What does the customer want?",
        "options": ["billing", "technical", "cancellation", "other"]
      },
      {
        "id": "urgency",
        "prompt": "How urgent is this?",
        "options": ["low", "normal", "high"]
      }
    ]
  }'

La respuesta

La respuesta replica los identificadores de tus preguntas. Para cada una recibes la opción ganadora, su confianza y la distribución de probabilidad completa con las opciones como claves. `degraded` es true cuando el modelo en vivo no estaba disponible y respondió el respaldo determinista.

{
  "ok": true,
  "model": "cloudflare/clef-flash",
  "degraded": false,
  "latencyMs": 412,
  "answers": [
    {
      "id": "intent",
      "option": "billing",
      "confidence": 0.91,
      "probabilities": { "billing": 0.91, "technical": 0.04, "cancellation": 0.03, "other": 0.02 }
    },
    {
      "id": "urgency",
      "option": "high",
      "confidence": 0.72,
      "probabilities": { "low": 0.06, "normal": 0.22, "high": 0.72 }
    }
  ]
}

Campos de la petición

Todos los campos se validan en el límite; una petición no válida se rechaza con un mensaje que nombra el valor problemático.

• state — cadena de 3 a 6.000 caracteres. Texto libre o una cadena JSON.
• questions — array de 1 a 8 objetos.
• questions[].id — slug en minúsculas, de hasta 32 caracteres, único dentro de la petición.
• questions[].prompt — la pregunta, de hasta 300 caracteres.
• questions[].options — de 2 a 12 respuestas permitidas, cada una de hasta 80 caracteres, sin duplicados.

Errores

Los errores devuelven un cuerpo JSON con `ok: false` y una cadena `error` legible.

• 400 — la petición estaba mal formada; el mensaje nombra el campo y el valor.
• 401 — se envió una clave de API pero es desconocida o ha sido revocada.
• 429 — la cuota diaria está agotada.
• 500 — algo falló por nuestra parte; es seguro reintentar la petición.

Cuotas

El nivel gratuito permite un número fijo de decisiones por sesión de navegador y día. Los niveles de pago elevan ese límite para las claves de API. El uso actual de una petición no se devuelve en la respuesta; pregunta al soporte si necesitas un informe de uso.

Ejemplos de cliente

La misma llamada en JavaScript y Python, ambas envían el cuerpo JSON anterior.

const response = await fetch('https://clef-flash.com/api/decide', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    authorization: `Bearer ${process.env.CLEF_FLASH_KEY}`,
  },
  body: JSON.stringify({
    state: ticketBody,
    questions: [{ id: 'queue', prompt: 'Which queue?', options: ['billing', 'technical', 'abuse'] }],
  }),
});
const { answers } = await response.json();
if (answers[0].confidence < 0.8) routeToHuman(ticketBody);
else routeTo(answers[0].option);

Cuándo preferir el autoalojamiento

Si el estado contiene datos que no pueden salir de tu infraestructura, ejecuta el modelo tú mismo: los pesos son Apache 2.0. La guía para ejecutarlo localmente cubre el hardware y el comando de Ollama. La forma de la petición es la misma, así que el código que escribas contra esta API se traslada directamente.