Skip to content

Referencia rápida de la API: solicitudes, respuestas y errores ​

Desde el inicio rápido hasta los escenarios prácticos, has estado trabajando todo el tiempo con lo mismo: el endpoint /v1/systemone de la API de TypeSafe. Esta página lo extrae y lo comprime en una tabla de referencia rápida: campos de solicitud, respuestas por tipo de pregunta, encabezados, reglas de solicitud, códigos de estado, todo consultable en una sola tabla. Ten esta página abierta mientras escribes código: es más rápido que revisar la documentación oficial de la API.

Qué podrás hacer al terminar ​

  • Decir los dos endpoints de la API de TypeSafe, el método de autenticación y los cuatro campos del cuerpo de solicitud (model / state / questions / assets)
  • Consultar por tipo de pregunta los campos exactos que devuelve cada respuesta (Choice / Score / Noul / Box)
  • Localizar errores con la tabla de códigos de estado: qué significa cada uno, de 400 a 529, y qué hay que cambiar
  • Saber cuándo hay que añadir encabezados TypeSafe-Danger-Zone-* y cuándo conviene escribir tus propios reintentos
  • Usar la tabla de métodos equivalentes del SDK para hacer las mismas llamadas en Python / JavaScript

Tu situación actual ​

  • Cada vez que escribes código tienes que volver a la lección de inicio rápido para copiar la estructura de la solicitud, sin una página de consulta directa
  • Cuando hay un error solo conoces el número del código de estado, sin saber si el cuerpo de solicitud está mal escrito o la Key es incorrecta
  • Tienes en la cabeza dos formas de escribirlo, curl directo y SDK, que chocan entre sí y los nombres de los campos no coinciden

Cuándo usar este recurso ​

Cuando necesitas:

  • Una página a mano para consultar sobre la marcha los campos y códigos de estado de la API de TypeSafe
  • Determinar rápidamente al depurar si «este 4xx es un problema mío o del servicio»

Y no quieres:

  • Repasar cada vez la documentación extensa de la referencia oficial de la API
  • Saltar entre varias páginas de tutoriales buscando la descripción del mismo campo

🎒 Preparativos antes de empezar ​

Idea central: un solo endpoint, todo parte de la estructura de la solicitud ​

Todos los modelos de la serie Jev son atendidos por el mismo endpoint: POST https://api.typesafe.ai/v1/systemone. El campo model de la solicitud determina qué modelo procesa la petición — no existe eso de «una URL por modelo».

La autenticación solo reconoce un encabezado:

http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的API Key>
Content-Type: application/json

Configura un endpoint auxiliar para «consultar qué modelos hay disponibles»:

bash
curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Deberías ver: un arreglo models, donde cada elemento incluye name, description, release_date (con valores de ejemplo como jev-latest, General-purpose system one model., 2026-09-15). El name obtenido se pone directamente en el campo model de la solicitud.

¿Cómo es el cuerpo de la solicitud? El ejemplo de ticket del inicio rápido oficial (versión con curl directo, extracto con dos preguntas; requiere curl 7.76+ y --fail-with-body para que también se imprima el cuerpo de la respuesta en caso de error):

bash
curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "state": "Our API integration started returning 500 errors...",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}
JSON

Toda la API tiene esta única forma. A continuación se desglosa bloque por bloque como referencia rápida.

Tabla completa de campos de solicitud ​

CampoObligatorioTipoDescripción
model✅CadenaNombre o alias del modelo; los nombres disponibles los devuelve GET /v1/models. Por ejemplo jev-latest, jev-preview
state✅Cadena / objeto JSON / arreglo de textosContenido evaluado en común por todas las preguntas. Las tres formas se detallan en Estado (State)
questions✅Objeto (al menos 1 pregunta)La clave es el ID de pregunta que tú eliges y el valor es el objeto de la pregunta; no hay límite en la cantidad de preguntas, la única restricción está en la longitud del contexto
assets❌objeto (mínimo 1 elemento)recursos de imagen, con las claves como marcadores de posición (la recomendación oficial es un UUID por imagen); al usar imágenes debe acompañarse del encabezado TypeSafe-Danger-Zone-Images: true

Campos del objeto de preguntas:

CampoObligatorioDescripción
ID (la clave del objeto)✅Lo eliges tú, para identificar la respuesta correspondiente en la respuesta; no se envía al modelo: la pregunta completa debe escribirse en instructions, aunque el ID parezca autoexplicativo
type✅choice / score / noul / box elegir uno de cuatro
instructionslos cuatro tipos de pregunta pueden omitirse en el schemaLa pregunta completa; puede ser una cadena, un objeto JSON o un array (la pregunta y los datos que referencia pueden ir por separado). El ID no se envía al modelo, así que en realidad debe escribirse en cada pregunta
criteriaObligatorio para Choice y ScoreChoice: map de opciones (1–255 elementos); Score: lista ordenada de niveles (1–10 elementos); Noul: definición opcional de true/false sí/no

Para referenciar campos de state en instructions, envuelve la ruta de puntos/subíndices con acentos graves, como `ticket.messages[0].text`; consulta la lección Estado (State).

Tabla completa de tipos de pregunta y campos de respuesta ​

En una sola solicitud se puede mezclar cualquier tipo de pregunta; todas las preguntas se evalúan en paralelo e independientemente sobre el mismo state (para un ejemplo extremo de este uso, ver preguntas en paralelo).

Tipo de preguntatype ValorForma de criteriaCampo de respuesta
Choicechoicemap de opciones, 1–255 elementoschoice (el nombre de la opción elegida, es decir, la de mayor probabilidad), confidence, probabilities (una probabilidad por opción, sumando no estrictamente 1)
Scorescorelista ordenada de niveles, 1–10 elementosscore (valor esperado ponderado por probabilidad, puede caer entre dos niveles, p. ej. 0.67 / 1.7), confidence, legend (mapeo de nivel a valor), probabilities
NoulnoulOpcional: definición de true/falsenoul (probabilidad de verdadero/sí de 0–1; cercano a 0.5 = incierto; sin campo confidence)
BoxboxNingunobox (top/bottom/left/right cuatro bordes, como proporción del alto/ancho de la imagen 0–1), confidence (puede ser null). Requiere imagen + activar el encabezado de imágenes

Cómo elegir el tipo de pregunta y el uso completo de cada uno:

Tabla completa de encabezados de solicitud ​

Encabezado de solicitudCuándo usarloDescripción
Authorization: Bearer <key>Cada solicitudAusente o inválido → 401
Content-Type: application/jsonSolicitudes de textoLas imágenes van por multipart/form-data: el JSON como primera parte (nombre request), una parte independiente por cada imagen
Content-Encoding: gzip o x-gzip / zstdComprimir cuerpos de solicitud grandesSolo se permite una capa; la ventana de zstd ≤ 8 MiB; no soportado o varias capas → 415, cuerpo comprimido corrupto → 400
TypeSafe-Danger-Zone-Images: trueCuando la solicitud incluye imágenes o preguntas BoxDebe incluirse en cada solicitud con imágenes; si falta → 400
TypeSafe-Danger-Zone-Long-Context: trueCuando el texto largo no cabe en el contexto por defectoTanto el contexto por solicitud como el por pregunta pasan a 262k; el precio no cambia, pero es más lento y menos preciso, úsalo solo en las solicitudes que lo necesiten

Límites de contexto por defecto (idénticos en Jev 1.14 y 1.13): por solicitud 64k / por pregunta 32k token; el número de preguntas en sí no tiene límite. Para una consulta rápida de precios y versiones de modelos, ver Modelos y precios.

Reglas de solicitud y compresión ​

La documentación oficial de errors define cuatro reglas estrictas para cada solicitud:

ReglaLímiteCódigo de estado por infracción
Tamaño del cuerpo de la solicitud≤ 32 MiB (sin incluir los header)413 (al superarse el límite cuenta tanto antes como después de la compresión)
CodificaciónJSON en UTF-8, sin BOM400
Anidamientostate / instructions / criteria cada uno con ≤ 64 niveles de objetos y arrays; lo más profundo se aplana primero400
Númerossolo se aceptan números finitos: NaN, Infinity, 1e400 y similares se rechazan; los números grandes y los ID se envían como cadenas400

La compresión solo añade dos reglas: un solo nivel como límite y zstd window ≤ 8 MiB.

Tabla completa de campos de respuesta ​

json
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 1.0,
      "probabilities": { "technical": 1.0, "billing": 0.0, "sales": 0.0 }
    },
    "frustration": {
      "type": "score",
      "score": 0.67,
      "confidence": 0.5,
      "legend": { "0": "Calm…", "1": "Frustrated…", "2": "Very angry…" },
      "probabilities": { "0": 0.33, "1": 0.67, "2": 0.0 }
    },
    "is_urgent": { "type": "noul", "noul": 0.99 }
  },
  "usage": { "input_tokens": 428, "output_tokens": 73 }
}

(valores de ejemplo, cambian según la versión; el ejemplo completo está en la lección primera solicitud.)

CampoUbicaciónDescripción
modelNivel superiorNombre del modelo que realmente respondió; puede diferir del alias usado en la solicitud (por ejemplo, se solicita jev-latest y se devuelve el número de versión concreto)
answersNivel superiorCorresponde uno a uno con los ID de las preguntas que planteaste; el type de cada respuesta coincide con el type de su pregunta
usage.input_tokensNivel superiorCantidad de tokens de entrada facturados en esta llamada (la facturación solo cuenta la entrada)
usage.output_tokensNivel superiorCantidad de tokens de salida, por ahora gratuita

Tabla completa de códigos de estado ​

Código de estadoSignificadoQué debes hacer
200ÉxitoObtén las respuestas por ID
400 Bad RequestInfracción de las reglas de solicitud (UTF-8 no válido, más de 64 niveles de anidamiento, números no finitos, cuerpo comprimido corrupto, falta la cabecera de imagen); max_tokens_exceeded = se superó la longitud del contextoCorrige el cuerpo de la solicitud según la tabla de «reglas de solicitud»; si se supera el contexto, reduce el state o activa la cabecera de contexto largo
401 UnauthorizedKey faltante o no válidaRevisa la cabecera Authorization; los usuarios del SDK revisan TYPESAFE_API_KEY (ver el aviso de errores comunes más abajo)
413 Payload Too LargeEl cuerpo de la solicitud supera 32 MiBReduce el state; la compresión no ayuda 413——32 MiB se aplica tanto antes como después de la compresión
415 Unsupported Media TypeContent-Encoding no soportado o compresión en varios nivelesUsa solo uno de gzip / x-gzip / zstd, en un solo nivel
422 Unprocessable EntityValidación del cuerpo de la solicitud fallida: faltan campos obligatorios, formato de pregunta incorrecto, etc.Consulta el array detail del body para localizar el problema
429 Too Many RequestsLímite de velocidad superado (por organización: tokens/s + requests/s; consultable en la consola console.typesafe.ai/rate-limits)Reintenta con backoff exponencial; el SDK lo gestiona automáticamente por defecto
529 OverloadedTypeSafe sobrecargado temporalmenteIgual que 429: reintenta tras el backoff

El body de 422 indica el campo exacto:

json
{
  "detail": [
    { "loc": ["body", "state"], "msg": "Field required", "type": "missing" }
  ]
}

Localiza el campo con error mediante loc; msg te dice qué falta.

Gestión de errores y reintentos ​

Regla oficial en una frase: al recibir 429 o 529, reintenta con backoff exponencial (alargando la espera progresivamente), sin reenviar de inmediato tal cual; si la respuesta incluye la cabecera retry-after, respétala.

Si usas el SDK: los SDK de Python / JavaScript incluyen por defecto una política de reintentos que gestiona automáticamente 429, sin código adicional. Si necesitas personalizarla (Python):

python
from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(retry=RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0))

Forma estándar de capturar errores de API en el SDK de Python:

python
from typesafe_sdk import TypeSafeAPIError

try:
    client.system_one(state, questions)
except TypeSafeAPIError as error:
    print(error.status, error.request_id)

error.status es el código de estado y error.request_id es el identificador de la solicitud—inclúyelos al reportar al soporte oficial.

Si te conectas directamente a la API: los reintentos los escribes tú. El --fail-with-body de curl al menos garantiza ver el cuerpo de la respuesta cuando hay error.

Resumen rápido de los dos clientes Python ​

La API TypeSafe usa el mismo nombre de método en los dos clientes de Python: TypeSafeClient (síncrono) y AsyncTypeSafeClient (asíncrono); ambos son system_one(). Variables de entorno que lee el SDK:

VariableFunciónValor por defecto
TYPESAFE_API_KEYAPI Key (obligatoria)—
TYPESAFE_BASE_URLURL raíz de la APIhttps://api.typesafe.ai
TYPESAFE_DEFAULT_MODELModelo por defectojev-latest
TYPESAFE_LOG_LEVELNivel de registro, se aplica una sola vez al importar typesafe_sdkNo establecido

Resumen rápido de respuestas en TypeScript ​

En el SDK de JS/TS (@typesafe-ai/sdk) las respuestas se obtienen directamente por ID: response.answers.department.choice, y los tipos se infieren de la definición de la pregunta (por ejemplo, "billing" | "technical" | "sales").

Aviso de errores comunes ​

❌ Se solicita jev-latest, pero el model de la respuesta no es él ​

No es un error: el model de la respuesta es el nombre del modelo que realmente respondió, que puede diferir del alias usado en la solicitud (la especificación oficial de la API lo indica claramente). Para ver a qué apunta el alias actualmente, consulta Modelos y precios.

❌ La Key se mezcla con espacios o saltos de línea ​

Con conexión directa, este tipo de Key siempre da 401. El SDK elimina los espacios en blanco al inicio y al final de la Key (incluidos los saltos de línea leídos de un archivo), pero los espacios internos, caracteres de control y no ASCII se rechazan directamente (el error se produce al crear el cliente, ni siquiera llega al 401); pasar una Key vacía explícitamente no recurre a las variables de entorno. Al copiar la Key desde la consola, no selecciones un espacio de más.

❌ Adivinar qué salió mal a partir del código de estado 422 ​

No adivines, lee el body: el loc del array detail es la ruta del campo (por ejemplo ["body", "questions", "urgency", "criteria"]), y msg es la razón.

❌ No se encuentra confidence en la respuesta de Noul ​

No se perdió: Noul naturalmente no tiene un campo confidence. Para unificar el umbral puedes calcular |2p − 1|; el punto de partida recomendado oficialmente: yes ≥ 0.7, no ≤ 0.3 (ver Preguntas de sí/no de Noul).

❌ Las llamadas de alta frecuencia a la API directa son inundadas por 429 ​

El límite de velocidad se cuenta por organización (tokens/s + requests/s). El SDK reintenta con retroceso por defecto; con conexión directa, escribe tu propio retroceso exponencial. Para una cuota mayor, usa el formulario oficial de solicitud (support.typesafe.ai).

Resumen de esta lección ​

✅ Un endpoint POST /v1/systemone, autenticación con un header, cuerpo de la solicitud con cuatro campos (model / state / questions / assets).

✅ Cuatro tipos de pregunta, cuatro tipos de respuesta: Choice devuelve opciones + probabilidades + confidence, Score devuelve puntuación esperada + legend, Noul solo devuelve la probabilidad 0–1, Box devuelve las proporciones de los cuatro lados.

✅ Códigos de estado de principio a fin: 400 reglas / 401 Key / 413 tamaño / 415 compresión / 422 validación (mira el body) / 429 529 reintento con retroceso.

✅ Dos headers de Danger Zone se añaden según necesidad: imágenes con TypeSafe-Danger-Zone-Images, contexto largo con TypeSafe-Danger-Zone-Long-Context.

Repaso de los campos de configuración clave:

CampoValor recomendadoDescripción
modeljev-latestAlias, actualmente apunta a Jev 1.14; para fijar la versión, escribe jev-1.14.0
stateCadena / objeto JSON / array de textoCualquiera de las tres formas
questions{ID: {type, instructions, criteria}}El ID no se envía al modelo; la pregunta completa va en instructions
Contexto64k / solicitud · 32k / preguntaCon el header de contexto largo, ambos son 262k
Cuerpo de la solicitudJSON UTF-8 ≤ 32 MiB · anidamiento ≤ 64 niveles · los números deben ser finitosCompresión con una capa gzip / zstd

Avance de la próxima lección ​

Ya sabes llamar a la API, ahora hay que entender la facturación: Modelos y precios: versiones, límites de contexto, tarifas.

Aprenderás:

  • jev-1.14.0 y jev-1.13.0: línea de tiempo de versiones y a qué apuntan los alias
  • $42/Btok: cómo se factura y por qué solo se cuentan los tokens de entrada
  • Los detalles de los límites de contexto y el costo del contexto largo
  • Cómo consultar los límites de velocidad y cómo solicitar un aumento de cuota

Tutoriales relacionados ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.