客户端 SDK | JoyToken

JoyToken 客户端 SDK 是当前公开开发者 API 的薄封装。SDK 负责认证请求头、请求类型、流式解析、模型列表和统一错误对象；应用自己的业务编排仍然留在你的代码里。

SDK 列表

语言	包名 / 模块	适合场景
TypeScript	`@joytoken/client-sdk-ts`	Node.js 服务、Next.js 后端路由、Agent runtime 和 worker
Go	`github.com/joytoken/client-sdk-golang`	Go 服务、后台 worker 和内部工具

两个 SDK 覆盖同一组公开 API：

能力	SDK 方法	接口
聊天补全	`chat.completions.create()` / `CreateChatCompletion()`	`POST /openai/v1/chat/completions`
流式聊天补全	`chat.completions.stream()` / `StreamChatCompletion()`	`POST /openai/v1/chat/completions`
模型目录	`models.list()` / `ListModels()`	`GET /api/v1/models`

安装

$ pnpm add @joytoken/client-sdk-ts

快速示例

1 import { JoyTokenClient } from "@joytoken/client-sdk-ts";
2 
3 const client = new JoyTokenClient({
4   apiKey: process.env.JOY_TOKEN_API_KEY,
5 });
6 
7 const response = await client.chat.completions.create({
8   model: "auto",
9   messages: [
10     { role: "user", content: "Explain JoyToken in one sentence." },
11   ],
12 });
13 
14 console.log(response.choices[0]?.message?.content);

什么时候使用客户端 SDK

当应用自己负责业务编排，并且需要一个类型化模型调用客户端时，使用客户端 SDK。

场景	为什么适合客户端 SDK
直接模型调用	一次调用得到一次模型响应
流式 UI	SDK 解析 SSE 事件，并暴露分块
服务端封装	统一 API Key、base URL、超时和 request ID
Agent runtime	作为自研循环下方的模型提供方层
模型选择器	从 `GET /api/v1/models` 读取公开模型目录

客户端 SDK 与 Agent SDK

	客户端 SDK	Agent SDK
关注点	类型化 API 客户端	多步 Agent runtime
模型调用	应用直接调用聊天补全	Agent SDK 调用模型提供方
工具	应用自己调度工具调用	Agent SDK 调度注册的工具
状态	应用保存 messages 和 checkpoints	应用仍负责持久化，Agent SDK 管理运行循环
语言	TypeScript、Go	TypeScript

下一步

页面	内容
编码 Agent 使用	让编码助手理解如何使用 JoyToken SDK
TypeScript SDK	安装、配置、调用、流式响应和错误处理
TypeScript API 参考	导出的 class、method 和核心类型
Go SDK	安装、配置、调用、流式响应和错误处理
Go API 参考	client options、methods、stream、errors 和 types