@tokincloud/sdk

Tokin 数据面 SDK。在 OpenAI 兼容调用之上，封装平台特有的那一层：app_id 归属 + 短期凭证透明续期 + 余额/用量回显。跨平台（Node 18+ / 浏览器），零运行时依赖（仅用标准 fetch）。

这是「自有 SDK 相对原生 OpenAI SDK 多做的事」。任何语言的官方 OpenAI SDK 改 base_url 也能直连网关，但拿不到自动续期、分润归属与余额回显——那正是本 SDK 的价值。

最省事：直接用 OpenAI 官方 SDK（任何语言，零我方依赖）

Tokin 的 /v1/chat/completions、/v1/models 完全 OpenAI 兼容。任何语言的官方 OpenAI 库，只要把 base_url 指向网关、api_key 换成用户的 sk-tokin-*，即刻可用（对话、流式、列模型全通）。不需要安装我们任何东西——现有 OpenAI 生态代码改一行 endpoint 即迁入。

• Base URL：https://api.tokincloud.com/v1
• API Key：用户在控制台生成的 sk-tokin-*（服务端使用；不要下发到不可信客户端）
• 模型名：见 /v1/models 或定价页

from openai import OpenAI
client = OpenAI(base_url="https://api.tokincloud.com/v1", api_key="sk-tokin-xxxx")
r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好，介绍一下自己"}],
)
print(r.choices[0].message.content)

using OpenAI.Chat;
using System.ClientModel;

var client = new ChatClient(
    model: "deepseek-v4-flash",
    credential: new ApiKeyCredential("sk-tokin-xxxx"),
    options: new OpenAI.OpenAIClientOptions { Endpoint = new Uri("https://api.tokincloud.com/v1") });

ChatCompletion done = client.CompleteChat("你好，介绍一下自己");
Console.WriteLine(done.Content[0].Text);

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.tokincloud.com/v1", apiKey: "sk-tokin-xxxx" });
const r = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "你好，介绍一下自己" }],
});
console.log(r.choices[0].message.content);

就是一个普通 POST + Authorization: Bearer sk-tokin-xxxx：

curl https://api.tokincloud.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tokin-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}]}'

Go 用 go-openai：config := openai.DefaultConfig("sk-tokin-xxxx"); config.BaseURL = "https://api.tokincloud.com/v1"。

什么时候需要我们的 SDK / 协议？ 当你想要①一键登录换短期令牌（OAuth PKCE，密码只留在我方域）②令牌自动续期 ③多 agent 抗辩 /v1/panel。这三样都是开放协议 + 普通 REST，任何语言都能照抄——官方维护 Node / Python / Java，C# / Go 等为社区可移植（见下方各语言 README 与 openapi/tokin-gateway.yaml）。

安装

npm i @tokincloud/sdk

三种登录入口（按场景挑一种）

import { TokinClient } from "@tokincloud/sdk";
const BASE = "https://api.tokincloud.com";

// ① 服务器 / CI（无浏览器）—— 最省事，直接用主 Key
const client = TokinClient.withApiKey(BASE, "sk-tokin-xxxx");

// ② 受信第一方工具 —— 手机号+密码登录，密码用完即弃，换短期凭证（可吊销、自动续期）
const client2 = await TokinClient.login(BASE, "13800000000", "••••••", { appId: "app_xxx" });

// ③ 桌面 / 本地 —— OAuth PKCE 一键连接：拉起浏览器授权，密码只留在 tokincloud.com
const client3 = await TokinClient.connect(BASE, "app_xxx");

对话（含图片）与多 agent

// 非流式
const res = await client.chat({ model: "deepseek-v4-flash", messages: [{ role: "user", content: "你好" }] });

// 流式
for await (const delta of client.chatStream({ model: "glm-5.2", messages: [{ role: "user", content: "数到三" }] })) {
  process.stdout.write(delta);
}

// 图片（本地路径或 URL 均可）
import { imageUrl } from "@tokincloud/sdk";
await client.chat({ model: "qwen3-vl-plus", messages: [{ role: "user", content: [
  { type: "text", text: "这张图是什么？" }, await imageUrl("cat.png"),
] as any }] });

// 多 agent 抗辩：一次调 N 个「不同厂商」模型，judge 再综合出裁判结论
const panel = await client.panel({ messages: [{ role: "user", content: "该不该上这个方案？" }], n: 3, judge: true });
panel.agents.forEach((a) => console.log(a.agent, a.model, a.content)); // 透明返回真实模型名
console.log("裁判：", panel.verdict?.model, panel.verdict?.content);

// 流式多 agent：N 栏实时对辩
for await (const ev of client.panelStream({ messages: [{ role: "user", content: "红蓝抗辩" }], n: 3, judge: true })) {
  if (ev.delta) process.stdout.write(`[${ev.agent}] ${ev.delta}`);
}

// 账户
await client.getBalance();   // { balance }
await client.getUsage();     // { count, totalSpent, records[] } —— 只含用户自己花费
await client.listModels();   // string[]

自动续期（透明）

所有调用前自动 ensureFresh（距过期 ≤5s 提前刷新），收到 401 再被动刷新重试一次；并发只触发一次刷新（单飞）；刷新会轮换 refresh_token。续期失败（被吊销/过期）抛 TokinAuthError，开发者捕获后引导用户重新授权。

多语言

后续以一份 OpenAPI 规范 codegen 出 Python / C# / Go 等客户端；本 TS 包为手工打磨的主力实现。

联网搜索与企业数据（同一个钱包，无需额外 Key）

// ① 让模型自己联网（仅通义千问系）——最省，且带**真实来源**
const r = await client.chat({
  model: "qwen-plus",
  messages: [{ role: "user", content: "今天上海天气?" }],
  enable_search: true,
});
for (const s of r.search_info?.search_results ?? []) {
  console.log(s.title, s.url);   // 搜索引擎返回的真实标题+URL，可入库核验
}

⚠ 正文里的 [1] 角标与链接是模型自己写的、可能是编的；要留痕、要核验，只信 search_info.search_results。 流式（chatStream）暂不返回 search_info。非 qwen 模型不支持联网，响应头会标 X-Tokin-Web-Search: unsupported。

// ② 独立搜索接口（任何模型都能配：先搜，再把结果喂给 deepseek 等）
const s = await client.search("2026 世界杯 举办地", { count: 5, freshness: "oneMonth" });

// ③ 企业数据：工商/风险/知产/裁判文书/标讯…共 185 个工具
await client.company({ keyword: "阿里巴巴" });                    // 简易：实体识别
await client.companyTools("risk");                                // 目录（免费），每项带 price/credits
await client.company({ server: "risk", tool: "工具名", arguments: { searchKey: "…" } });

await client.services();   // 增值服务目录：单价、是否已接通

按次计费，与模型调用同一个钱包/代付/X-Usage-Tag 分组；调用失败或查无结果不收费。