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
400a529, 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
- Ya has completado tu primera solicitud: instalar el SDK de Python y enviar la primera solicitud (o conexión directa con curl)
- La API Key está en la variable de entorno
TYPESAFE_API_KEY - Si no logras instalarlo o ejecutarlo, ve primero a solución de problemas del inicio — esta página solo sirve como referencia rápida, no como guía de depuración paso a paso
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:
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的API Key>
Content-Type: application/jsonConfigura un endpoint auxiliar para «consultar qué modelos hay disponibles»:
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):
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"
}
}
}
JSONToda la API tiene esta única forma. A continuación se desglosa bloque por bloque como referencia rápida.
Tabla completa de campos de solicitud
| Campo | Obligatorio | Tipo | Descripción |
|---|---|---|---|
model | ✅ | Cadena | Nombre o alias del modelo; los nombres disponibles los devuelve GET /v1/models. Por ejemplo jev-latest, jev-preview |
state | ✅ | Cadena / objeto JSON / arreglo de textos | Contenido 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:
| Campo | Obligatorio | Descripció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 |
instructions | los cuatro tipos de pregunta pueden omitirse en el schema | La 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 |
criteria | Obligatorio para Choice y Score | Choice: 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 pregunta | type Valor | Forma de criteria | Campo de respuesta |
|---|---|---|---|
| Choice | choice | map de opciones, 1–255 elementos | choice (el nombre de la opción elegida, es decir, la de mayor probabilidad), confidence, probabilities (una probabilidad por opción, sumando no estrictamente 1) |
| Score | score | lista ordenada de niveles, 1–10 elementos | score (valor esperado ponderado por probabilidad, puede caer entre dos niveles, p. ej. 0.67 / 1.7), confidence, legend (mapeo de nivel a valor), probabilities |
| Noul | noul | Opcional: definición de true/false | noul (probabilidad de verdadero/sí de 0–1; cercano a 0.5 = incierto; sin campo confidence) |
| Box | box | Ninguno | box (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:
- Choice, pregunta de selección · Score, pregunta de puntuación · Noul, pregunta de sí/no · Box e imágenes
- Cómo se calcula confidence y cómo fijar el umbral: Confianza (Confidence)
Tabla completa de encabezados de solicitud
| Encabezado de solicitud | Cuándo usarlo | Descripción |
|---|---|---|
Authorization: Bearer <key> | Cada solicitud | Ausente o inválido → 401 |
Content-Type: application/json | Solicitudes de texto | Las 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 / zstd | Comprimir cuerpos de solicitud grandes | Solo se permite una capa; la ventana de zstd ≤ 8 MiB; no soportado o varias capas → 415, cuerpo comprimido corrupto → 400 |
TypeSafe-Danger-Zone-Images: true | Cuando la solicitud incluye imágenes o preguntas Box | Debe incluirse en cada solicitud con imágenes; si falta → 400 |
TypeSafe-Danger-Zone-Long-Context: true | Cuando el texto largo no cabe en el contexto por defecto | Tanto 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:
| Regla | Límite | Có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ón | JSON en UTF-8, sin BOM | 400 |
| Anidamiento | state / instructions / criteria cada uno con ≤ 64 niveles de objetos y arrays; lo más profundo se aplana primero | 400 |
| Números | solo se aceptan números finitos: NaN, Infinity, 1e400 y similares se rechazan; los números grandes y los ID se envían como cadenas | 400 |
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
{
"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.)
| Campo | Ubicación | Descripción |
|---|---|---|
model | Nivel superior | Nombre 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) |
answers | Nivel superior | Corresponde 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_tokens | Nivel superior | Cantidad de tokens de entrada facturados en esta llamada (la facturación solo cuenta la entrada) |
usage.output_tokens | Nivel superior | Cantidad de tokens de salida, por ahora gratuita |
Tabla completa de códigos de estado
| Código de estado | Significado | Qué debes hacer |
|---|---|---|
200 | Éxito | Obtén las respuestas por ID |
400 Bad Request | Infracció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 contexto | Corrige 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 Unauthorized | Key faltante o no válida | Revisa la cabecera Authorization; los usuarios del SDK revisan TYPESAFE_API_KEY (ver el aviso de errores comunes más abajo) |
413 Payload Too Large | El cuerpo de la solicitud supera 32 MiB | Reduce el state; la compresión no ayuda 413——32 MiB se aplica tanto antes como después de la compresión |
415 Unsupported Media Type | Content-Encoding no soportado o compresión en varios niveles | Usa solo uno de gzip / x-gzip / zstd, en un solo nivel |
422 Unprocessable Entity | Validació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 Requests | Lí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 Overloaded | TypeSafe sobrecargado temporalmente | Igual que 429: reintenta tras el backoff |
El body de 422 indica el campo exacto:
{
"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):
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:
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:
| Variable | Función | Valor por defecto |
|---|---|---|
TYPESAFE_API_KEY | API Key (obligatoria) | — |
TYPESAFE_BASE_URL | URL raíz de la API | https://api.typesafe.ai |
TYPESAFE_DEFAULT_MODEL | Modelo por defecto | jev-latest |
TYPESAFE_LOG_LEVEL | Nivel de registro, se aplica una sola vez al importar typesafe_sdk | No 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:
| Campo | Valor recomendado | Descripción |
|---|---|---|
model | jev-latest | Alias, actualmente apunta a Jev 1.14; para fijar la versión, escribe jev-1.14.0 |
state | Cadena / objeto JSON / array de texto | Cualquiera de las tres formas |
questions | {ID: {type, instructions, criteria}} | El ID no se envía al modelo; la pregunta completa va en instructions |
| Contexto | 64k / solicitud · 32k / pregunta | Con el header de contexto largo, ambos son 262k |
| Cuerpo de la solicitud | JSON UTF-8 ≤ 32 MiB · anidamiento ≤ 64 niveles · los números deben ser finitos | Compresió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.0yjev-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
- Qué hacer si no se instala o no funciona: resolución de problemas inicial——la versión completa para diagnosticar error por error
- Instalar el SDK de Python y enviar la primera solicitud——explicación paso a paso de la estructura de la solicitud
- Métodos alternativos de instalación: uv, npm y conexión directa a la API con curl——el recorrido completo de la conexión directa con curl