Client SDKs
TypeScript SDK
@hypershub/sdk — 官方 TypeScript/Node.js 客户端, 支持 Chat Completions、Responses、Anthropic Messages、Gemini generateContent / streamGenerateContent 和 Models,兼容 Node.js ≥ 18 和现代浏览器。
安装
npm install @hypershub/sdk初始化
创建一个 HypersHub 实例。 推荐通过环境变量传入 API Key,避免硬编码到源码中。
import { HypersHub } from '@hypershub/sdk'
// 从环境变量自动读取 HYPERSHUB_API_KEY
const client = new HypersHub()
// 或显式传入
const client = new HypersHub({
apiKey: 'sk-hy-...',
baseURL: 'https://apiclaw.cc', // 可选,默认值
})| 参数 | 类型 | 说明 |
|---|---|---|
| apiKey | string | 平台 API Key,默认读取 HYPERSHUB_API_KEY 环境变量 |
| baseURL | string | API 地址,默认 https://apiclaw.cc |
| defaultHeaders | Record<string, string> | 附加到每次请求的自定义 Header |
Chat Completions
与 OpenAI Chat API 完全兼容,支持 Claude、GPT、Gemini 等所有模型。
const res = await client.chat.completions.create({
model: 'claude-sonnet-4-6',
messages: [
{ role: 'system', content: '你是一个专业的技术顾问。' },
{ role: 'user', content: '解释一下什么是 RAG?' },
],
})
console.log(res.choices[0].message.content)
console.log('Token 用量:', res.usage)Responses
调用 OpenAI Responses 风格接口,适合新的文本生成、结构化输出与多轮响应编排。
const response = await client.responses.create({
model: 'gpt-5.4',
input: '用一句话介绍 HypersHub。',
max_output_tokens: 256,
})
console.log(response.output)
console.log('Token 用量:', response.usage)Anthropic Messages
通过原生 Anthropic Messages API 调用 Claude 模型,支持 Extended Thinking 和多轮对话。
const msg = await client.messages.create({
model: 'claude-opus-4-7',
max_tokens: 1024,
system: '你是一个专业的代码审查助手,只输出简洁的技术反馈。',
messages: [
{ role: 'user', content: '帮我审查:function add(a,b){return a+b}' },
],
})
const block = msg.content[0]
if (block.type === 'text') console.log(block.text)Gemini generateContent
通过 Google Gemini 原生格式调用模型,支持多模态输入和流式输出。
const res = await client.gemini.generateContent({
model: 'gemini-3.1-pro-preview',
contents: [
{ role: 'user', parts: [{ text: '用 Python 写一个冒泡排序。' }] },
],
generationConfig: { maxOutputTokens: 1024, temperature: 0.7 },
})
const text = res.candidates[0].content.parts[0]
if ('text' in text) console.log(text.text)Models
查询可用模型列表,或按 path 中的 model ID 获取单个模型详情。
const models = await client.models.list()
for (const model of models.data) {
console.log(model.id)
}错误处理
所有 API 错误均抛出继承自 HypersHubError 的类型化错误, 可通过 status 字段精准处理。
import {
HypersHub,
HypersHubAuthError,
HypersHubRateLimitError,
HypersHubInsufficientBalanceError,
HypersHubError,
} from '@hypershub/sdk'
try {
const res = await client.chat.completions.create({ /* ... */ })
} catch (err) {
if (err instanceof HypersHubAuthError) {
console.error('API Key 无效,请检查密钥配置')
} else if (err instanceof HypersHubRateLimitError) {
console.error('请求频率超限,请稍后重试')
} else if (err instanceof HypersHubInsufficientBalanceError) {
console.error('账户余额不足,请充值')
} else if (err instanceof HypersHubError) {
console.error(`API 错误 ${err.status}: ${err.message}`)
} else {
throw err
}
}| 错误类 | HTTP 状态码 | 触发原因 |
|---|---|---|
| HypersHubAuthError | 401 | API Key 无效或已过期 |
| HypersHubInsufficientBalanceError | 402 | 账户余额不足 |
| HypersHubRateLimitError | 429 | 请求频率或并发超出限制 |
| HypersHubError | 其他 4xx / 5xx | 通用 API 错误基类 |
请求取消
所有方法的第二个参数均接受 AbortSignal,可用于超时或用户主动取消。
// 10 秒超时
const controller = new AbortController()
const timeout = setTimeout(() => controller.abort(), 10_000)
try {
const res = await client.chat.completions.create(
{ model: 'claude-sonnet-4-6', messages: [{ role: 'user', content: '...' }] },
controller.signal,
)
} finally {
clearTimeout(timeout)
}Parameters
所有公开方法的完整参数与返回值说明。
chat.completions.create()
client.chat.completions.create(params, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | 模型 ID,例如 claude-sonnet-4-6、gpt-5.4、gemini-3.1-pro-preview。 |
| messages | ChatMessage[] | ✓ | 对话历史,支持 system / developer / user / assistant / tool 角色。 |
| stream | boolean | — | true 返回 AsyncGenerator<ChatCompletionChunk>,false(默认)返回 ChatCompletion。 |
| tools | Tool[] | — | Function Calling 工具定义,type 固定为 "function"。 |
| tool_choice | string | object | — | "none" | "auto" | "required" 或 { type: "function", function: { name } }。 |
| reasoning_effort | "low"|"medium"|"high" | — | 推理强度,仅部分模型支持。 |
| temperature | number | — | 采样温度,取值 0–2;推理模型固定为 1。 |
| top_p | number | — | 核采样概率,取值 0–1。 |
| presence_penalty | number | — | 存在惩罚,取值 -2–2。 |
| frequency_penalty | number | — | 频率惩罚,取值 -2–2。 |
| max_completion_tokens | number | — | 最大输出 token 数,建议优先使用此字段。 |
| max_tokens | number | — | 兼容字段,网关自动转换为 max_completion_tokens。 |
| response_format | object | — | { type: "text" | "json_object" },指定输出格式。 |
| stop | string | string[] | — | 停止词,命中后截断输出。 |
| user | string | — | 终端用户标识,用于平台侧监控。 |
| signal | AbortSignal | — | (第二个参数)传入 AbortController.signal 可取消请求。 |
responses.create()
client.responses.create(params, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | 模型 ID,例如 gpt-5.4、claude-sonnet-4-6。 |
| input | string | array | ✓ | 输入文本或消息数组。 |
| stream | boolean | — | true 返回 AsyncGenerator<ResponseStreamEvent>,默认返回 ModelResponse。 |
| instructions | string | — | 系统级指令。 |
| max_output_tokens | number | — | 最大输出 token 数。 |
| reasoning_effort | "low"|"medium"|"high" | — | 推理强度,仅部分模型支持。 |
| temperature | number | — | 采样温度。 |
| tools | Tool[] | object[] | — | 工具定义。 |
| text | object | — | 文本输出格式配置,支持 text / json_object / json_schema。 |
| previous_response_id | string | — | 上一轮 response ID,用于多轮衔接。 |
| signal | AbortSignal | — | (第二个参数)传入 AbortController.signal 可取消请求。 |
messages.create()
client.messages.create(params, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | Claude 模型 ID,例如 claude-opus-4-7、claude-sonnet-4-6。 |
| messages | MessageParam[] | ✓ | 对话数组,role 取值为 "user" 或 "assistant"。 |
| max_tokens | number | ✓ | 最大输出 token 数。 |
| system | string | object[] | — | 系统提示词;可为字符串或 [{ type: "text", text }] 数组。 |
| stream | boolean | — | true 返回 AsyncGenerator<MessageStreamEvent>。 |
| thinking | object | — | { type: "enabled", budget_tokens: number },启用 Extended Thinking。 |
| tools | AnthropicTool[] | — | 工具定义,含 name、description、input_schema。 |
| tool_choice | object | — | { type: "auto"|"any"|"none" } 或 { type: "tool", name }。 |
| temperature | number | — | 采样温度 0–1;启用 thinking 时须为 1。 |
| top_p | number | — | 核采样概率。 |
| top_k | number | — | Top-K 采样。 |
| stop_sequences | string[] | — | 停止词数组,命中即截断输出。 |
| metadata | { user_id?: string } | — | 用于平台侧用户标识。 |
| signal | AbortSignal | — | (第二个参数)传入 AbortController.signal 可取消请求。 |
gemini.generateContent()
client.gemini.generateContent(params, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | 模型 ID,例如 gemini-3.1-pro-preview。 |
| contents | Content[] | ✓ | 对话内容,每项含 role("user"|"model")和 parts 数组。 |
| stream | boolean | — | true 返回 AsyncGenerator<GenerateContentResponse>,默认返回单次完整响应。 |
| systemInstruction | Content | — | 系统指令,格式同 contents,role 通常省略。 |
| tools | GeminiTool[] | — | 工具定义,含 function_declarations 数组。 |
| generationConfig | GenerationConfig | — | 生成参数,见下表。 |
| signal | AbortSignal | — | (第二个参数)传入 AbortController.signal 可取消请求。 |
GenerationConfig 字段
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| temperature | number | — | 采样温度。 |
| topP | number | — | 核采样概率。 |
| topK | number | — | Top-K 采样。 |
| maxOutputTokens | number | — | 最大输出 token 数。 |
| stopSequences | string[] | — | 停止词数组。 |
| responseMimeType | string | — | 输出 MIME 类型,例如 "application/json"。 |
| candidateCount | number | — | 候选回复数量,通常为 1。 |
| thinkingConfig | object | — | { thinkingBudget?: number },启用思维链。 |
gemini.streamGenerateContent()
client.gemini.streamGenerateContent(params, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | 模型 ID,会写入 /v1beta/models/{model}:streamGenerateContent 的 path。 |
| contents | Content[] | ✓ | 对话内容,每项含 role 和 parts 数组。 |
| systemInstruction | Content | — | 系统指令。 |
| tools | GeminiTool[] | — | 工具定义。 |
| generationConfig | GenerationConfig | — | 生成参数。 |
| signal | AbortSignal | — | (第二个参数)传入 AbortController.signal 可取消请求。 |
models
client.models.list(signal?)client.models.retrieve(model, signal?)| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | ✓ | 仅 retrieve 必填;模型 ID,会写入 /v1/models/{model} 的 path。 |
| signal | AbortSignal | — | 传入 AbortController.signal 可取消请求。 |

