Referencia de la API

Referencia completa de la API HTTP del endpoint de evaluación de TypeSafe.

Evalúa un state contra un mapa de questions tipadas y recibe answers estructuradas, una por pregunta. Para una introducción guiada, empieza por las primitivas.

Endpoint de evaluación

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

Cuerpo de la solicitud

La forma de nivel superior de cada solicitud. Cada entrada del mapa questions es una pregunta tipada a la que tú pones nombre.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

Tipos de pregunta

Un Question es uno de tres tipos, definido por su campo type. Los tres comparten type e instructions; cada uno añade su propio criteria.

La propiedad instructions puede ser una cadena, un objeto o un array. Puedes dividir una pregunta larga que tenga contexto adicional, o datos a los que necesite referirse, en un objeto estructurado. Pon la pregunta en un campo y los datos en los demás, y refiérete a los campos de datos por su nombre entre comillas invertidas, igual que apuntas una pregunta a un valor anidado de state:

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

Consulta Usar estructura en las preguntas para saber más.

Noul

Una pregunta de sí/no. Devuelve la probabilidad de que la respuesta sea sí.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

Elige una opción de un conjunto que tú defines. Devuelve la opción elegida y la distribución de probabilidad completa.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

Puntúa el estado según una rúbrica que tú defines. Devuelve un valor ponderado por probabilidad a través de tus niveles.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

Cuerpo de la respuesta

Una respuesta por pregunta, devuelta bajo los mismos ids que proporcionaste.

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

Tipos de respuesta

Cada respuesta lleva un type que coincide con su pregunta. Las respuestas de Choice y Score también llevan una confidence entre 0 y 1, derivada de la distribución de probabilidad de la respuesta. Consulta Confidence.

Respuesta Noul

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Respuesta Choice

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Respuesta Score

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

Errores

Los errores usan códigos de estado HTTP estándar con un cuerpo JSON que describe qué salió mal.

Cómo manejar los límites de uso

Cuando recibas una respuesta 429 Too Many Requests o 529 Overloaded, reintenta la solicitud con retroceso exponencial en lugar de reintentar de inmediato. Nuestros SDK de cliente lo manejan automáticamente, así que no hace falta ningún manejo adicional si usas uno de nuestros SDK con su política de reintentos predeterminada.