Una API de salida estructurada que responde dentro de tu esquema
Si le pides JSON a un modelo generativo, todavía tienes que comprobarlo. Esta API invierte la tarea: tú declaras las respuestas que existen y el modelo devuelve una distribución sobre ellas.
Lo que todavía cuesta la «salida estructurada»
La generación restringida por esquema ha facilitado obtener JSON válido, pero la validez es solo la primera propiedad de una respuesta útil. Las preguntas difíciles son si la etiqueta es una que declaraste, si la respuesta está dentro de las opciones enumeradas y cuánta seguridad tenía el modelo.
Un modelo de decisión responde a eso por construcción, porque el espacio de salida es la pregunta que hiciste. Envías preguntas tipadas —una elección sobre un conjunto cerrado de etiquetas, un sí/no como una única probabilidad, una puntuación sobre niveles ordenados— y recibes una probabilidad para cada respuesta permitida.
- La etiqueta devuelta siempre es una que declaraste en la solicitud.
- Cada opción vuelve con su probabilidad, incluidas las que pierden.
- La forma no puede desviarse entre llamadas, porque es la solicitud y no un prompt.
Salida estructurada, JSON mode y llamadas a herramientas
Ninguna de las tres es estrictamente mejor; responden a preguntas distintas. JSON mode es la herramienta correcta cuando la respuesta es un documento: un resumen, un borrador, un registro con campos de texto libre. La API de decisión es la herramienta correcta cuando la respuesta es una elección entre opciones acotadas.
| Enfoque | Lo que obtienes | Lo que sigue siendo tuyo |
|---|---|---|
| JSON mode | JSON bien formado cuando el modelo cumple | Validación, reintentos y acuerdo sobre qué significa cada campo |
| Llamada a herramientas | Un nombre de función y sus argumentos | La herramienta, el esquema y el caso en que el modelo no llama a nada |
| API de decisión | Una distribución sobre las respuestas que declaraste | Un umbral y la acción que hay detrás de cada respuesta |
Garantías que el cliente puede comprobar
Cada respuesta nombra el modelo y el proveedor que la produjeron, la latencia y un requestId. La respuesta de cada pregunta lleva el tipo con el que se preguntó, así que quien la consume puede ramificar por tipo sin adivinar.
- Toda opción declarada aparece en probabilities y la distribución suma uno.
- Una respuesta de tipo choice nombra una etiqueta de la solicitud, nunca una nueva.
- Una respuesta de tipo score se queda dentro de sus niveles y devuelve un número, no un cajón elegido de antemano.
- Una negativa es un estado, un código estable y un requestId, nunca un 200 vacío.
Los fallos forman parte del contrato
Cuando el proveedor no puede responder, esta API devuelve 502 model_unavailable y no cobra nada. El puntuador léxico determinista solo se ejecuta si lo pides con allowDegraded: true, y entonces la respuesta dice degraded: true y nombra el fallback como proveedor. A quien se le prometió una decisión del modelo nunca se le entrega en silencio otro tipo de decisión.
Cuándo es la herramienta equivocada
Si la respuesta es un párrafo, una edición de código o una extracción abierta, un modelo de decisión es la forma equivocada: usa un modelo que escriba. Esta API sirve para elecciones acotadas: enrutar, etiquetar, puntuar, moderar y decidir si algo pasa. El esquema es el punto; cuando no hay un conjunto cerrado que enumerar, aquí no hay ventaja.
Preguntas frecuentes
¿Es lo mismo que JSON mode?
No. JSON mode restringe la sintaxis; esta API restringe el conjunto de respuestas. Recibes una probabilidad para cada opción que declaraste, y la respuesta ganadora es una de ellas por construcción.
¿Puedo recibir texto libre?
No desde este endpoint, por diseño. Si la salida es prosa, usa un modelo generativo; la página de modelo de decisión frente a LLM explica dónde está la frontera.
¿Qué tipos de pregunta admite?
Elección sobre un conjunto cerrado, noul (un sí/no como una probabilidad) y score sobre niveles ordenados. El endpoint con clave acepta preguntas tipadas con instructions y criteria; el gratuito acepta prompt y options.
¿Qué pasa si el modelo no puede asignar su respuesta al esquema?
La llamada falla como 502 model_unavailable y no se cobra nada. La API no repara la respuesta, no adivina una etiqueta y no devuelve un cuerpo a medias.
Sigue leyendo
- Documentación de la API
- Cinco ejemplos ejecutables
- API de clasificación con IA
- Modelo de decisión vs LLM
Notas del modelo
Un correo corto cuando salga un nuevo modelo de decisión o cambie un benchmark. Sin spam, baja en un clic.