Registro y API Key: obtén la llave de TypeSafe en 5 minutos
En la lección anterior ya sabes qué es Jev. En esta lección obtienes la llave en mano: completa el registro en TypeSafe, entra en la consola para crear una Jev API Key, guárdala en una variable de entorno y valida con el Playground oficial que realmente funciona; todo en 5 minutos, sin escribir una sola línea de código.
Qué podrás hacer al terminar
- Completar el registro en TypeSafe e iniciar sesión en la consola TypeSafe console
- Crear una Jev API Key en la página Keys de la consola
- Guardar la Key en la variable de entorno
TYPESAFE_API_KEYpara que el SDK la lea automáticamente - Enviar una solicitud real con Playground y confirmar que la Key funciona
- Saber dónde consultar los límites de tasa y qué ocurre al superarlos
Tu situación actual
- Quieres probar Jev, pero no sabes dónde obtener la Key: hay un montón de entradas en el sitio web, la documentación y la consola, y tras dar vueltas un buen rato no encuentras dónde se genera
- Copiaste la Key en el código y funcionó una vez, y al ir a hacer el commit en git te dio un susto de muerte
- Has oído que hay límites de tasa, pero no sabes cuál es tu cuota ni qué pasa si la superas
Cuándo usar esta técnica
Cuando necesitas:
- Una Jev API Key capaz de invocar
api.typesafe.ai - Una forma de validar si la Key funciona sin escribir código
Y además no quieres:
- Escribir la clave en texto plano en el código o el repositorio
- Devorar toda la documentación del API antes de lograr tu primera solicitud
🎒 Preparativos antes de empezar
- Haber leído la lección anterior Jev qué es y saber que la forma de invocar a Jev es «state + pregunta»
- Un navegador moderno (el registro, la creación de la Key y la validación en Playground se hacen enteramente en el navegador)
- Una red con acceso a
console.typesafe.ai(la consola) y aapi.typesafe.ai(el API)
Idea central
Solo hay una llave y una sola entrada. Todas las invocaciones a Jev —SDK, curl, Playground— pasan por el mismo API y se autentican con la misma API Key. Por eso el flujo es corto: registrarse → generar la Key en la consola → guardarla en una variable de entorno → validar.
Por qué guardarla en una variable de entorno. La recomendación oficial es explícita: tras generar la Key, guárdala en una variable de entorno (como TYPESAFE_API_KEY). Dos ventajas:
- El SDK oficial lee esta variable automáticamente, así que no hace falta escribir ninguna clave en el código
- Si la Key no acaba en los archivos de código, no saldrá en los commits de git
Las tres páginas de la consola TypeSafe console, cada una a cargo de una cosa.
| Página | Dirección | Para qué sirve |
|---|---|---|
| Keys | console.typesafe.ai/keys | Crear la API Key |
| Playground | console.typesafe.ai/playground | Enviar solicitudes reales sin código, validar la Key |
| Rate limits | console.typesafe.ai/rate-limits | Consultar los límites de tasa de la organización actual |
Una gestión de expectativas. Jev se encuentra actualmente en fase de acceso anticipado; las palabras textuales del sitio oficial son «Try our first System One Model, Jev, in early access». La interfaz de la consola puede cambiar según la versión; esta lección solo se ancla a las direcciones y al flujo indicados en la documentación oficial, y los detalles de la interfaz deben tomarse de la página real.
⚠️ Nota para usuarios de China continental
Las fuentes oficiales no incluyen indicaciones sobre el acceso desde redes de China continental ni el pago en yuanes; esta lección no da consejos que no se puedan verificar; si encuentras problemas de acceso o de pago, sigue las indicaciones de las páginas oficiales de TypeSafe.
Hazlo conmigo
Paso 1: completa el registro en TypeSafe e inicia sesión en la consola
Por qué: las API Key solo se emiten en la consola de TypeSafe, así que primero necesitas una cuenta.
Abre console.typesafe.ai en el navegador y sigue las indicaciones de la página para registrarte e iniciar sesión.
Deberías ver: la interfaz de la consola. En la navegación del sitio oficial esta entrada se llama «API console».
Paso 2: crea tu Jev API Key en la página Keys
Por qué: las palabras textuales del inicio rápido oficial son «Get an API key from the TypeSafe console», y se refieren precisamente a esta página, Keys.
Abre console.typesafe.ai/keys y sigue las indicaciones de la página para crear una nueva Key.
Deberías ver: una cadena de texto con la clave. Cópiala primero en un lugar local temporal, porque la vas a usar en el siguiente paso.
- Copié la Key y no la pegué en ningún archivo de código
Paso 3: guarda la Key en una variable de entorno TYPESAFE_API_KEY
Por qué: la recomendación oficial es guardar la Key en una variable de entorno; el SDK de Python la lee automáticamente de TYPESAFE_API_KEY, así que la clave no tiene que aparecer en el código.
La forma que muestra el inicio rápido oficial (Bash en macOS / Linux / Windows WSL):
export TYPESAFE_API_KEY="your-api-key"Sustituye your-api-key por la cadena de clave que acabas de copiar.
Deberías ver: que el comando no produce ninguna salida tras ejecutarse—export, cuando tiene éxito, es silencioso.
💡 Este comando solo tiene efecto en la terminal actual
La variable definida con export desaparece al cerrar la terminal, y tendrás que ejecutarlo de nuevo la próxima vez que abras una nueva. Para dejarlo resuelto de una vez, puedes añadirlo a tu archivo de configuración del shell (por ejemplo ~/.bashrc)—esto es un uso general del shell que TypeSafe no cubre en su documentación oficial.
- Ejecuté el export en la terminal actual y el nombre de la variable es
TYPESAFE_API_KEY
Paso 4: verifica esta Key con el Playground
Por qué: antes de escribir código, confirma que la Key funciona—el Playground envía solicitudes reales directamente desde el navegador, sin instalar nada.
- Abre console.typesafe.ai/playground e inicia sesión
- Pega este ticket de ejemplo oficial en la zona de state:
Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.- Añade la pregunta Noul del ejemplo oficial:
{
"urgency": {
"type": "noul",
"instructions": "Does this message express urgency?"
}
}Deberías ver: un número de probabilidad entre 0 y 1. Si obtienes un número, significa que el registro, la Key y la red funcionan—esta llave sirve.
- En el Playground obtuve un número entre 0–1
Paso 5: echa un vistazo a tus límites de velocidad
Por qué: los límites de velocidad de Jev se calculan por organización, y las solicitudes que exceden el límite devuelven 429; saber de antemano dónde consultar tu cuota te da tranquilidad cuando más adelante ejecutes tareas por lotes.
Abre console.typesafe.ai/rate-limits.
Deberías ver: los límites de la organización actual, medidos en dos dimensiones: tokens por segundo (tokens/s) y solicitudes por segundo (requests/s).
Punto de control ✅
- Puedo iniciar sesión en la consola de TypeSafe y sé que la Key se crea en la página
/keys - Guardé mi Key en la variable de entorno
TYPESAFE_API_KEYy no la escribí en el código - En el Playground obtuve con esta Key una probabilidad de 0–1
- Sé que los límites de velocidad se consultan en la página
/rate-limitsy que excederlos devuelve429 - Sé que el SDK oficial lee automáticamente
TYPESAFE_API_KEY
Aviso sobre errores comunes
❌ Escribir la Key directamente en el código o subirla a git
Una vez que la clave entra en el repositorio, borrar el commit ya no basta—cualquiera puede tomar una Key filtrada y quemar tu cuota. La forma correcta: guardarla en la variable de entorno TYPESAFE_API_KEY (recomendación oficial), escribir en el código solo TypeSafeClient(model="jev-latest"), y el SDK la leerá por sí mismo.
❌ La solicitud devuelve 401
401 = falta la Key o no es válida. Revisa tres cosas en orden: si hiciste export en la terminal actual; si el nombre de la variable es TYPESAFE_API_KEY (todo en mayúsculas, sin errores de escritura); y si la Key copiada lleva contenido extra. El SDK oficial elimina los espacios en blanco al inicio y al final de la Key (incluidos los saltos de línea), pero si la Key contiene espacios, caracteres de control o caracteres no ASCII en su interior, se rechaza directamente.
❌ Creer que la Key está rota porque la solicitud devuelve 429
429 = se activó el límite de velocidad, no es un problema de la Key. El límite se calcula por organización (tokens/s + requests/s); consulta la cuota en la página /rate-limits. El SDK oficial reintenta automáticamente por defecto (el tiempo de espera se alarga en cada intento y respeta la cabecera de respuesta retry-after); solo necesitas gestionarlo tú mismo si te conectas directamente a la API HTTP. Para una cuota mayor, recurre a los planes custom / enterprise; hay un formulario de solicitud oficial.
❌ Perderse en la consola
Con recordar tres páginas basta: /keys para crear la Key, /playground para probarla y /rate-limits para consultar los límites—es más rápido escribir la URL directamente en la barra de direcciones.
Técnicas avanzadas (opcional)
Configura también esta Key para tu coding agent. La documentación oficial del agent skill menciona expresamente: crea una API Key, dale permiso a tu coding agent y deja que, con llamadas de prueba baratas, explore por sí mismo el mejor uso de TypeSafe. Además, ofrecen un prompt listo para usar—«ejecuta algunos experimentos con la Key que exporté a TYPESAFE_API_KEY y propón cambios basados en los resultados más prometedores». Combinado con el skill TypeSafe de la lección Desarrollo con Claude Code, el agent puede escribir directamente por ti el código que llama a Jev.
La relación entre la Key y los precios. Esta Key cobra por token al llamar a Jev—la entrada se cobra, la salida es gratis. La tabla completa de tarifas, versiones de modelos y límites de contexto está en la página Modelos y precios.
Resumen de la lección
✅ Registro completado en TypeSafe: ya tienes cuenta en la consola de TypeSafe; la Key se crea en la página /keys.
✅ Key lista: guardada en la variable de entorno TYPESAFE_API_KEY, leída automáticamente por el SDK oficial, con cero claves en el código.
✅ Key verificada: en el Playground obtuviste una probabilidad real; y sabes que los límites de velocidad se consultan en /rate-limits.
Repaso de los campos de configuración clave:
| Campo | Valor recomendado | Descripción |
|---|---|---|
TYPESAFE_API_KEY | Tu Key (variable de entorno) | Forma de almacenamiento recomendada oficialmente; el SDK de Python la lee automáticamente |
| Página de creación de la Key | console.typesafe.ai/keys | Página Keys de la consola |
| Playground | console.typesafe.ai/playground | Verifica la Key y prueba tipos de preguntas sin código |
| Página de límites de velocidad | console.typesafe.ai/rate-limits | Por organización: tokens/s + requests/s; al superar el límite se devuelve 429 |
Avance de la próxima lección
Ya tienes la llave; en la próxima lección la pondremos en uso: instalar el SDK de Python y enviar la primera solicitud: 10 minutos para que funcione.
Aprenderás a:
- Instalar typesafe-sdk con venv + pip (Python 3.10+)
- Ejecutar el ejemplo oficial de las tres preguntas del ticket de soporte, obteniendo de una vez clasificación, puntuación y respuesta de sí/no
- Entender
probabilitiesyconfidenceen la respuesta - Qué revisar primero cuando la instalación falla o la ejecución no funciona