两行代码，接入所有大模型

内部工具、自研服务、原型验证：用你自己账号的余额跑，不必实名、不必注册应用、不必上架。

日后要转成"用户各自付费"，只需补认证 + 换授权那段代码，模型调用部分不动。

丢进项目 libs/，加进 classpath 即可（零第三方依赖）。Maven 中央仓库即将上线。

# 装进本地 Maven 仓库后即可引用：
mvn install:install-file \
  -Dfile=tokin-sdk-0.2.0.jar \
  -DgroupId=ai.tokin -DartifactId=tokin-sdk \
  -Dversion=0.2.0 -Dpackaging=jar

import ai.tokin.TokinClient;

TokinClient tokin = new TokinClient("dev_abax_jz");
String reply = tokin.chat("tokin-balanced", "帮我记一笔：午餐 35 元");

// 没绑定？自动弹浏览器让用户注册授权
// 绑定后自动续期，永久免登录

不想注册账号也能拿到正式 app_id——见下方「应用标识自助管理」。

dev_ 开头的标识免注册、直接能用，适合本地联调。但它不保证唯一——别人用同一个字符串可能抢先绑走你的回调，所以对外跑请用上面的匿名注册拿正式 app_。正式对外发布时到控制台创建应用换成 app_（16 位随机、他人无法占用，授权页显示你的应用名而不是裸标识）——其余代码一行不用改。

# 领一个正式 app_id。免鉴权、不用账号、不用实名。
# Idempotency-Key 可选（不带也能注册）。做重试的话强烈建议带：
# 这个接口发出去的标识收不回，重试必须安全。key 要在多次重试之间保持不变。
POST /v1/apps/register
  Idempotency-Key: <你生成的唯一串>
  {"name":"你的应用名"}
# → 201 { app_id, app_secret }   注意是 201 不是 200
# → 带同一个 Key 重放：200 + idempotent_replay:true，返回同一个 app
# → 请求体不合法或缺 name：400 invalid_body（不会默默发号）

# 绑定回调地址：部署时在**你的服务器上**调一次（app_secret 不要交给浏览器）
POST /v1/apps/bind-redirect    {"app_id","app_secret","redirect_uri"}
# → 200 {ok, redirect_uri, already}   already=true 表示本来就绑好了（重复部署安全）

# 换域名/换端口：先解绑，再重新 bind-redirect
POST /v1/apps/unbind-redirect  {"app_id","app_secret"}

# secret 泄露：用旧 secret 直接换，不需要账号
POST /v1/apps/rotate-secret    {"app_id","app_secret",
                                "grace_seconds": 0}   # 可选，见下

# 改名：持 app_secret 随时可改
POST /v1/apps/rename           {"app_id","app_secret","name"}

# 领错了/探针误建：未认领、无授权、无用量的可以删
POST /v1/apps/delete           {"app_id","app_secret"}

# 想进控制台管理（上架、看统计）：认领到你的账号名下
POST /v1/apps/claim            {"app_id","app_secret"}   # 需登录态

tokin.chatStream(model, msgs,
  delta -> print(delta));         // 流式：打字机效果，强烈推荐
tokin.balance();                  // 余额（元）
tokin.topupUrl();                 // 充值页，放个按钮打开它
tokin.auth().switchAccount();     // 换用户
tokin.auth().setApiKey("sk-tokin-…"); // 手动绑定（备用）

控制台 →「上传应用」，选安装包(exe/apk)、填版本号(如 1.3.0)+ 更新说明。平台自动做安全检查,通过即上架应用商店供下载;下载地址固定不变:

https://tokincloud.com/store/download/<appId>

发新版就是「传个更新版本号的新包」——下载地址不变,老用户下次查更新即可拿到。

机制:平台当"更新源",你的 App 启动时查一下、有新版就下载安装(只有 App 自己能装自己)。

// Java：SDK 一行查更新
var u = TokinClient.checkUpdate(
  "https://api.tokincloud.com", "dev_abax_jz", "1.2.0");
if (u != null && u.hasUpdate()) {
  // 下载 u.downloadUrl()，SHA-256 校验 u.hash()，再拉起安装
  Desktop.getDesktop().browse(URI.create(u.downloadUrl()));
}

任意语言:直接 GET /store/apps/<appId>/latest → 返回 {version, downloadUrl, releaseNotes, hash},版本不同就下载安装。

tools / tool_choice 全量透传上游，响应 tool_calls 原样返回，流式同理。在售文本模型（DeepSeek / 通义 / 智谱 / Kimi / 豆包 / MiniMax）基本都支持。

{ "model": "deepseek-flash",
  "messages": [...],
  "tools": [{ "type":"function",
    "function": { "name":"add_expense", ... } }],
  "tool_choice": "auto" }

tool 消耗计入正常 usage 计费，无额外费用。

messages 放 OpenAI 标准 image_url，http(s) 地址或 data:image/…;base64, 均可。推荐：qwen3-vl-flash(便宜) / qwen3-vl-plus / qwen-vl-max / glm-5v-turbo。

{ "role": "user", "content": [
  { "type":"text", "text":"识别这张发票" },
  { "type":"image_url", "image_url":
    { "url":"data:image/png;base64,..." } } ] }

图片 token 计入输入价计费。注意：图片别太小（几像素会被上游拒）；base64 带完整前缀。

POST /v1/chat/completions
{ "model": "qwen-plus",
  "messages": [{"role":"user","content":"今天上海天气?"}],
  "enable_search": true,
  "search_options": { "forced_search": true }  # 可选，默认已强制联网
}

# 响应在标准结构上多一个 search_info：
{ "choices":[…], "usage":{…},
  "search_info": { "search_results": [
    { "title": "…", "url": "https://…" }, … ] } }

响应头 X-Tokin-Web-Search: native 表示本次真的联网了。

计费：token 照常计费，另加一笔检索费（与 POST /v1/search 同价，见 GET /v1/services），只在真的联网并拿到结果时收，金额在响应头 X-Tokin-Search-Billing 里。检索由搜索引擎按次收费，不含在模型 token 里。

搜索结果作为输入 token 计费：天气类问题约 2000 输入 token（≈¥0.002），人物/新闻类约 5000（≈¥0.004）。比独立搜索接口便宜。

防幻觉建议：在 prompt 里明确「只依据检索结果作答，未覆盖的写『未检索到』，绝不编造链接/日期/数字」。

curl https://api.tokincloud.com/v1/audio/transcriptions   -H "Authorization: Bearer sk-tokin-…"   -F file=@lecture.mp3   -F response_format=verbose_json   -F prompt="吉布斯抽样,卡尔曼滤波"   # 领域词表，显著降错字

# → { text, duration, segments:[
#      { start: 0.48, end: 3.43, text: "…",
#        speaker: 0, words:[{word,start,end}] } ] }

response_format：json(默认) / verbose_json(带时间戳) / text / srt / vtt。后两个直接就是字幕文件。

# 长录音：流式上传 + 异步（参数走 query）
curl -X POST "…/v1/audio/transcriptions?async=true&response_format=srt"   -H "Content-Type: audio/mpeg" --data-binary @lecture.mp3
# → 202 { task_id, poll: "/v1/audio/transcriptions/{id}" }

GET /v1/audio/transcriptions/{task_id}?response_format=srt
# → 202 处理中 ／ 200 结果

按音频时长计费，转出多少字都不加钱。响应头 X-Tokin-Audio-Seconds / X-Tokin-Billing 回显本次秒数与金额。90 分钟的课约 ¥0.44。

// 凭证走 query：浏览器无法给 WS 设 Authorization 头
const ws = new WebSocket(
  "wss://api.tokincloud.com/v1/realtime/transcriptions"
  + "?token=sk-tokin-…&sample_rate=16000&format=pcm");

ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  // session.started → transcript(多次) → billing
  if (m.type === "transcript")
    render(m.text, m.is_final, m.begin_time, m.end_time);
};
// 上行：二进制帧 = 音频块；说完发 {"type":"finish"}
ws.send(pcmChunk);
ws.send(JSON.stringify({ type: "finish" }));

音频建议 16kHz 单声道 PCM，每 100ms 一块（3200 字节）。也支持 opus/mp3/aac 等，用 format 指定。

# 推荐：先换一次性连接票（凭证不进 URL、不落 nginx 日志）
POST /v1/realtime/ticket   // 带 Authorization
# → { ticket:"rt_…", expires_in:60 }
# 再握手：wss://api.tokincloud.com/v1/realtime/transcriptions?ticket=rt_…

{"type":"session.started", model, sample_rate}
{"type":"transcript", text, is_final,
 begin_time, end_time}      // 毫秒
{"type":"billing", seconds, amount,
 final}                     // 每结算一次一条
{"type":"error", message, code}

按音频秒数，¥0.00024/秒 × 加价倍率 → 一节 90 分钟的课约 ¥1.3。比课后文件转写（约 ¥0.44）贵，换来的是实时。

POST /v1/search
{ "query": "2026 世界杯 举办地", "count": 10,
  "freshness": "noLimit" }   # 可选 oneDay/oneWeek/oneMonth/oneYear

# → { results:[{title,url,snippet,publishedTime?,siteName?}],
#     billing:{service:"web-search",amount} }

给模型喂实时信息的标配：搜索 → 把 results 拼进 prompt → 再调 /v1/chat/completions。query ≤200 字符，count 1–20；snippet 已是长摘要，可直接入 prompt。

# 简易：按关键词查企业（自动走「实体识别」）
POST /v1/company
{ "keyword": "阿里巴巴" }

# 进阶：先看工具目录，再精确调任一工具
GET  /v1/company/tools?server=risk   # 目录免费
POST /v1/company
{ "server":"risk", "tool":"工具名", "arguments":{…} }

# → { result:…, billing:{service:"company-search",amount} }

数据来自企业信息服务商，共 185 个原子工具。服务可选：company / risk / ipr / operation / history / executive / regulation / case / tender / document。「客户尽调 / 合同相对方核验 / 供应商体检」直接搭。

按工具计价：不同工具单价不同（约 ¥0.1~¥2 / 次），GET /v1/company/tools 的每个工具都带 price 字段，调用前即可知价；实际扣费以响应里的 billing.amount 为准。查无结果也按同价计费（响应里 billing.noMatch=true）——数据源按次消耗额度，与是否查到无关。上游调用失败则不收费。

# 服务端生成并暂存（按 state 索引本站用户）
verifier  = base64url(random(32))
challenge = base64url(sha256(verifier))
state     = random()
store[state] = { user_id, verifier }   # 5~10 分钟过期

# 302 跳转用户浏览器到：
https://tokincloud.com/authorize.html
  ?app_id=dev_yourapp
  &redirect_uri=https://你的域名/oauth/callback
  &code_challenge={challenge}&state={state}

非 loopback 回调需先登记：PUT /v1/apps/<app_id>/redirects（用开发者本人的 sk-tokin-* 主 Key，不是终端用户的）。

# GET /oauth/callback?code=..&state=..
{ user_id, verifier } = store.pop(state)   # state 不匹配即拒绝

POST https://api.tokincloud.com/oauth/token
{ "grant_type":"authorization_code",
  "code": code, "code_verifier": verifier }
# → { access_token, refresh_token, expires_in, token_type }

db.save(user_id, refresh_token, access_token,
        expires_at = now + expires_in)

if now >= expires_at - 60:
    POST /oauth/token
    { "grant_type":"refresh_token",
      "refresh_token": db.get(user_id) }
    # refresh_token 每次刷新都会轮换 → 必须回写覆盖

// 请求（二选一）
{ "grant_type":"authorization_code",
  "code":"...", "code_verifier":"..." }
{ "grant_type":"refresh_token",
  "refresh_token":"..." }

// 响应 200
{ "access_token":  "...",   // Bearer 用它调 /v1
  "refresh_token": "...",   // 每次刷新都轮换，务必覆盖保存
  "expires_in":    900,     // 秒（access 有效期）
  "token_type":    "Bearer" }

// 失败 401
{ "error":"invalid_grant", "message":"..." }

refresh_token 无固定过期。支持轮换宽限期：多副本服务并发刷新时，30 秒内用同一个旧值重复刷新会回放上次结果（返回同一个新 refresh_token），不会误判为盗用；超过 30 秒的重放仍按泄露处理、吊销整条授权，所以务必以最新值覆盖保存。

{ "object":"list", "data":[
  { "id":"tokin-balanced", "object":"model-mode",
    "description":"速度效果均衡（默认）" },
  { "id":"deepseek-flash", "object":"model",
    "owned_by":"deepseek" } ] }

按 object 区分：model-mode=语义模式，model=具体模型。只列当前已上架可调用的，可直接用于选择器与可用性校验。

// GET /v1/balance
{ "balance": 12.3456 }        // 单位：元（人民币），可为小数

// GET /v1/usage
{ "count": 42, "totalSpent": 1.234,
  "records": [ { "ts":…, "provider":"deepseek",
    "model":"deepseek-flash", "promptTokens":…,
    "completionTokens":…, "spent":0.0021 } ] }

所有端点（含 /oauth/token）错误体统一为 {"error":{"message","type","code"}}，只写一套解析即可；OAuth 端点额外在顶层保留 code 字段兼容旧客户端。

POST /v1/chat/completions
{ "model":"deepseek-flash",
  "messages":[…], "stream": true }

# 响应 Content-Type: text/event-stream
data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: {"choices":[…],"usage":{…}}   # 见右
data: [DONE]

按行读，取 data: 后的 JSON；遇 [DONE] 结束。非 JSON 帧（心跳等）忽略即可。

按班级 / 课程 / 项目分组对账。平台不解释标签含义，只做聚合（≤64 字符）。多维标签的约定：一个字符串装多层、用 . 分隔，报表用 prefix 过滤任一层。

POST /v1/chat/completions
X-Usage-Tag: course_abc.feature_note   # 第一层=班级，第二层=功能

# 查询聚合（含调用次数与 token 数——判断"变多"还是"变贵"）
GET /v1/usage/by-tag?days=30
# → { tags:[{tag,calls,tokensIn,tokensOut,spent,lastUsedAt}] }

# 前缀过滤：course_abc. 开头 = 这个班的全部功能
GET /v1/usage/by-tag?days=30&prefix=course_abc.
# 按天分桶（做周报/月报客户端按天汇总即可）
GET /v1/usage/by-tag?days=30&bucket=day
# → { tags:[{tag,day:"2026-08-13",calls,…}] }（标签×天，Asia/Shanghai）

# 机构视角（看自己代付的成员，按标签分），同样支持 prefix/bucket
GET /v1/sponsor/usage/by-tag?days=30
# → { tags:[{tag,calls,members,tokensIn,tokensOut,spent}] }

标签会不会被别人"污染"？不会——以上报表都按「你的账号 / 你代付的成员」聚合，从不按 app 汇总；即使有人用了与你相同的 dev_ 标识和标签，也进不了你的报表（app 维度的平台统计才会混，这是尽早注册 app_ 的又一理由）。

用语义模式（tokin-balanced 等）时，响应头会明示真实模型，便于留痕与复现：

X-Tokin-Served-Model: deepseek-flash  # 实际模型
X-Tokin-Served-By:    deepseek           # 实际厂商
X-Tokin-Mode:         tokin-balanced     # 你传的模式（仅模式调用时）
X-Tokin-Failover:     true               # 发生了故障转移（仅转移时）

直接指定具体模型时，返回体 model 字段即为实际模型。流式同样带这些响应头（胜出候选在首帧确定后才开流），流式与非流式可共用一套"读响应头"代码。

# 带 redirect_uri 时 → 原样回跳并带上：
{redirect_uri}?error=access_denied&state={state}

# 无 redirect_uri（桌面手动复制场景）
# → 停在我们页面显示"已取消授权"，不回跳

回调里请同时处理 code 与 error 两种参数；state 一律原样带回。

授权页向用户明示：该应用仅可代其发起模型调用并从钱包扣费；拿不到账户密码或主密钥，不能提现、不能改账户、不能读取其它数据；凭证可随时在控制台一键吊销。

面向学校 / 家长解释时可直接引用这段。