注册与 API Key：5 分钟拿到 TypeSafe 钥匙

上一课你已经知道 Jev 是什么了。这节课把钥匙拿到手：完成 TypeSafe 注册，进控制台创建一把 Jev API Key，存进环境变量，再用官方 Playground 验证它真的能用——全程 5 分钟，不写一行代码。

学完你能做什么

• 完成 TypeSafe 注册，登录 TypeSafe console 控制台
• 在控制台 Keys 页创建一把 Jev API Key
• 把 Key 存进环境变量 TYPESAFE_API_KEY，让 SDK 自动读取
• 用 Playground 发一次真请求，确认 Key 可用
• 知道速率限制去哪查、超限了会发生什么

你现在的困境

• 想试 Jev，但不知道 Key 在哪拿：官网、文档、控制台一堆入口，转了半天没找到生成的地方
• Key 复制进代码里跑通了一次，回头提交 git 才惊出一身冷汗
• 听说有速率限制，但不知道自己的额度是多少、超了会怎样

什么时候用这一招

当你需要：

• 一把能调用 api.typesafe.ai 的 Jev API Key
• 一个不写代码就能验证 Key 好不好使的办法

而且不想：

• 把密钥明文写进代码或仓库
• 跑通第一个请求前先啃完整本 API 文档

🎒 开始前的准备

• 读完上一课 Jev 是什么，知道 Jev 的调用形态是「state + 问题」
• 一个现代浏览器（注册、创建 Key、Playground 验证，全程在浏览器里完成）
• 能访问 console.typesafe.ai（控制台）和 api.typesafe.ai（API）的网络

核心思路

钥匙只有一把，入口只有一个。 Jev 的所有调用——SDK、curl、Playground——都走同一个 API，认证都用同一把 API Key。所以流程很短：注册 → 控制台生成 Key → 存进环境变量 → 验证。

为什么存环境变量。 官方明确建议：生成 Key 后存进环境变量（如 TYPESAFE_API_KEY）。两个好处：

• 官方 SDK 会自动读这个变量，代码里一个密钥都不用写
• Key 不落进代码文件，就不会跟着 git 提交出去

TypeSafe console 三个页面，各管一件事。

页面	地址	用来干什么
Keys	console.typesafe.ai/keys	创建 API Key
Playground	console.typesafe.ai/playground	免代码发真请求，验证 Key
Rate limits	console.typesafe.ai/rate-limits	查当前组织的速率限额

一个预期管理。 Jev 目前处于早期访问阶段——官网原话是「Try our first System One Model, Jev, in early access」。控制台界面可能随版本调整，本课只锚定官方文档写明的地址与流程，界面细节以实际页面为准。

⚠️ 国内用户注意

官方信息源里没有关于国内网络访问、人民币支付的说明，本课不给无法核实的建议；如遇访问或付款问题，以 TypeSafe 官方页面提示为准。

跟我做

第 1 步：完成 TypeSafe 注册，登录控制台

为什么：API Key 只在 TypeSafe 控制台里发放，先得有账号。

浏览器打开 console.typesafe.ai，按页面提示注册并登录。

你应该看到：进入控制台界面。这个入口在官网导航里叫「API console」。

第 2 步：在 Keys 页面创建你的 Jev API Key

为什么：官方快速开始的原话是「Get an API key from the TypeSafe console」，指的就是 Keys 这一页。

打开 console.typesafe.ai/keys，按页面提示创建一把新 Key。

你应该看到：一串密钥文本。先复制到本地暂存，下一步就要用。

• 我复制下了 Key，并且没有把它贴进任何代码文件

第 3 步：把 Key 存进环境变量 TYPESAFE_API_KEY

为什么：官方建议 Key 存环境变量；Python SDK 会自动读 TYPESAFE_API_KEY，代码里不用出现密钥。

官方快速开始的写法（macOS / Linux / Windows WSL 的 Bash）：

export TYPESAFE_API_KEY="your-api-key"

把 your-api-key 换成你刚复制的那串密钥。

你应该看到：命令执行后没有任何输出——export 成功时就是安静的。

💡 这条命令只对当前终端有效

export 设置的变量在关掉终端后就没了，下次开新终端要重新执行。想一劳永逸，可以把它加进你的 shell 配置文件（如 ~/.bashrc）——这是通用 shell 用法，TypeSafe 官方文档没有涉及。

• 我在当前终端执行了 export，变量名是 TYPESAFE_API_KEY

第 4 步：用 Playground 验证这把 Key

为什么：写代码之前先确认 Key 可用——Playground 在浏览器里直接发真请求，不装任何东西。

1. 打开 console.typesafe.ai/playground 并登录
2. 把下面这段官方示例工单贴进 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.

3. 添加官方示例的 Noul 问题：

{
  "urgency": {
    "type": "noul",
    "instructions": "Does this message express urgency?"
  }
}

你应该看到：返回一个 0 到 1 之间的概率数字。拿到数字，就说明注册、Key、网络全通了——这把钥匙能用。

• 我在 Playground 里拿到了一个 0–1 之间的数字

第 5 步：查一眼你的速率限制

为什么：Jev 的速率限制按组织计算，超限的请求会返回 429；先知道额度在哪查，后面跑批量任务时心里有数。

打开 console.typesafe.ai/rate-limits。

你应该看到：当前组织的限额，按每秒 token 数（tokens/s）和每秒请求数（requests/s）两个维度计量。

检查点 ✅

• 我能登录 TypeSafe console，并知道 Key 在 /keys 页创建
• 我的 Key 存进了环境变量 TYPESAFE_API_KEY，没有写进代码
• 我在 Playground 用这把 Key 拿到过一个 0–1 的概率
• 我知道速率限制在 /rate-limits 页查，超限返回 429
• 我知道官方 SDK 会自动读 TYPESAFE_API_KEY

踩坑提醒

❌ 把 Key 硬编码进代码或提交进 git

密钥一旦进仓库，就算删掉提交也来不及——泄露的 Key 任何人都能拿去烧你的额度。正确做法：存环境变量 TYPESAFE_API_KEY（官方建议），代码里只写 TypeSafeClient(model="jev-latest")，SDK 自己会读。

❌ 请求返回 401

401 = Key 缺失或无效。按顺序查三处：当前终端是否 export 过；变量名是不是 TYPESAFE_API_KEY（全大写，别拼错）；复制的 Key 有没有带多余内容。官方 SDK 会剥掉 Key 首尾的空白（含换行），但 Key 内部有空格、控制字符或非 ASCII 字符会直接被拒。

❌ 请求返回 429 就以为 Key 坏了

429 = 触发速率限制，不是 Key 的问题。限额按组织计（tokens/s + requests/s），去 /rate-limits 页看额度。官方 SDK 默认自动重试（等待时间逐次拉长，并遵循 retry-after 响应头）；只有直连 HTTP API 才需要自己处理。要更高额度，走 custom / enterprise 计划，官方有申请表单。

❌ 在控制台里迷路

三个页面记住就行：/keys 建 Key、/playground 试 Key、/rate-limits 查限额——直接在地址栏输网址最快。

进阶技巧（可选）

给 coding agent 也配这把 Key。 官方 agent skill 文档专门提到：创建一把 API Key，给你的 coding agent 权限，让它用便宜的测试调用自己摸索 TypeSafe 的最佳用法。官方还给了现成 prompt——「用我导出到 TYPESAFE_API_KEY 的 Key 跑些实验，基于最有希望的结果提改动」。配合 与 Claude Code 配合开发 课的 TypeSafe skill，agent 能直接帮你写调用 Jev 的代码。

Key 与价格的关系。 这把 Key 调用 Jev 按 token 计费——输入计费、输出免费。费率、模型版本与上下文限制的完整表格在 模型与价格 页。

本课小结

✅ TypeSafe 注册完成：你有 TypeSafe console 账号了，Key 在 /keys 页创建。

✅ Key 已就位：存在环境变量 TYPESAFE_API_KEY，官方 SDK 自动读取，代码零密钥。

✅ Key 已验证：Playground 里拿到过真实概率；速率限制知道去 /rate-limits 查。

关键配置字段回顾：

字段	推荐值	说明
TYPESAFE_API_KEY	你的 Key（环境变量）	官方建议的存放方式；Python SDK 自动读取
Key 创建页	console.typesafe.ai/keys	控制台 Keys 页
Playground	console.typesafe.ai/playground	免代码验证 Key、试题型
速率限制页	console.typesafe.ai/rate-limits	按组织计：tokens/s + requests/s，超限返回 429

下一课预告

钥匙到手，下一课把它用起来：安装 Python SDK 并发出第一个请求：10 分钟跑通。

你会学到：

• 用 venv + pip 完成 typesafe-sdk 安装（Python 3.10+）
• 跑通官方工单三问示例，一次拿到分类、打分、是非三个答案
• 看懂返回里的 probabilities 和 confidence
• 装不上、跑不通时先查哪里