Tutorial de la OpenAI Decisions API: tu primera llamada de decisión

Paso 1 — consigue una clave

Abre el playground y pulsa Run una vez — se crean solos una sesión de invitado, una clave API y 1 crédito gratis. Para producción, inicia sesión y crea una clave con nombre en el panel, en API keys. Las claves se envían en la cabecera Authorization Bearer..

Mantén la clave en el servidor. Toda petición que la lleva se cobra a tu saldo, así que nunca la pongas en código de navegador ni en un repo público.

Paso 2 — envía la primera petición

Una petición de decisión tiene tres campos: model (decisions-1 o decisions-latest), state (el contexto que lee el modelo — una cadena, objeto JSON o array de texto) y questions (un mapa de 1 a 6 ids de pregunta). Escribe la pregunta real en instructions — el id es solo la etiqueta bajo la que vuelve la respuesta.

Una pregunta noul es un juicio de sí/no: el campo de respuesta noul es la probabilidad de que el enunciado sea cierto.

curl https://decisions-api.net/api/v1/decisions \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "decisions-1",
  "state": "I was charged twice for my subscription this morning.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}'

Paso 3 — añade una pregunta choice

Una pregunta choice elige una etiqueta de la lista que defines. criteria es un objeto de 2 a 8 ids de opción, cada uno con una descripción corta — el modelo lee la descripción, así que escríbela como una regla de enrutado.

Una pregunta score funciona igual pero toma un array ordenado de 2 a 10 descripciones de nivel, de menor a mayor. Puedes mezclar los tres tipos en una llamada, hasta seis preguntas.

{
  "team": {
    "type": "choice",
    "instructions": "Which team should own this ticket?",
    "criteria": {
      "payments": "Checkout, billing, or payment processing.",
      "frontend": "Rendering or browser behavior.",
      "account": "Login, permissions, or profile."
    }
  }
}

Paso 4 — lee las probabilidades

Una respuesta correcta trae model, answers indexadas por tus ids de pregunta, usage y credits_used. Una respuesta noul es solo la probabilidad. Una respuesta choice incluye el choice ganador, una probabilidad por opción y un valor de confianza.

El segundo puesto importa tanto como el ganador. Dos opciones cerca de 0.5 cada una no es lo mismo que 0.9 contra 0.1 — trata los casos ajustados como candidatos a revisión, no como aciertos.

{
  "model": "decisions-1",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "credits_used": 1
}

Paso 5 — fija un umbral y maneja errores

Elige un umbral de confianza con tu propio tráfico: acepta por encima, manda el resto a una persona. Empieza alto (0.7–0.8) y bájalo solo tras revisar los casos que no llegaron.

402 significa saldo agotado; 429 o 502 significa reintentar más tarde — las llamadas fallidas no se cobran. 422 es un error de validación del cuerpo y el mensaje nombra el campo.

const res = await fetch('https://decisions-api.net/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})

if (res.status === 402) { /* out of credits */ }
if (res.status === 429 || res.status === 502) { /* retry later */ }

const { answers } = await res.json()
const team = answers.team

if (team.type === 'choice' && team.confidence >= 0.7) {
  routeTo(team.choice)          // confident: auto-assign
} else {
  queueForHuman(team)           // low confidence or near-tie: review
}

Preguntas frecuentes