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', // 可选,默认值
})
参数类型说明
apiKeystring平台 API Key,默认读取 HYPERSHUB_API_KEY 环境变量
baseURLstringAPI 地址,默认 https://apiclaw.cc
defaultHeadersRecord<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 状态码触发原因
HypersHubAuthError401API Key 无效或已过期
HypersHubInsufficientBalanceError402账户余额不足
HypersHubRateLimitError429请求频率或并发超出限制
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?)
参数类型必填说明
modelstring模型 ID,例如 claude-sonnet-4-6、gpt-5.4、gemini-3.1-pro-preview。
messagesChatMessage[]对话历史,支持 system / developer / user / assistant / tool 角色。
streambooleantrue 返回 AsyncGenerator<ChatCompletionChunk>,false(默认)返回 ChatCompletion。
toolsTool[]Function Calling 工具定义,type 固定为 "function"。
tool_choicestring | object"none" | "auto" | "required" 或 { type: "function", function: { name } }。
reasoning_effort"low"|"medium"|"high"推理强度,仅部分模型支持。
temperaturenumber采样温度,取值 0–2;推理模型固定为 1。
top_pnumber核采样概率,取值 0–1。
presence_penaltynumber存在惩罚,取值 -2–2。
frequency_penaltynumber频率惩罚,取值 -2–2。
max_completion_tokensnumber最大输出 token 数,建议优先使用此字段。
max_tokensnumber兼容字段,网关自动转换为 max_completion_tokens。
response_formatobject{ type: "text" | "json_object" },指定输出格式。
stopstring | string[]停止词,命中后截断输出。
userstring终端用户标识,用于平台侧监控。
signalAbortSignal(第二个参数)传入 AbortController.signal 可取消请求。

responses.create()

client.responses.create(params, signal?)
参数类型必填说明
modelstring模型 ID,例如 gpt-5.4、claude-sonnet-4-6。
inputstring | array输入文本或消息数组。
streambooleantrue 返回 AsyncGenerator<ResponseStreamEvent>,默认返回 ModelResponse。
instructionsstring系统级指令。
max_output_tokensnumber最大输出 token 数。
reasoning_effort"low"|"medium"|"high"推理强度,仅部分模型支持。
temperaturenumber采样温度。
toolsTool[] | object[]工具定义。
textobject文本输出格式配置,支持 text / json_object / json_schema。
previous_response_idstring上一轮 response ID,用于多轮衔接。
signalAbortSignal(第二个参数)传入 AbortController.signal 可取消请求。

messages.create()

client.messages.create(params, signal?)
参数类型必填说明
modelstringClaude 模型 ID,例如 claude-opus-4-7、claude-sonnet-4-6。
messagesMessageParam[]对话数组,role 取值为 "user" 或 "assistant"。
max_tokensnumber最大输出 token 数。
systemstring | object[]系统提示词;可为字符串或 [{ type: "text", text }] 数组。
streambooleantrue 返回 AsyncGenerator<MessageStreamEvent>。
thinkingobject{ type: "enabled", budget_tokens: number },启用 Extended Thinking。
toolsAnthropicTool[]工具定义,含 name、description、input_schema。
tool_choiceobject{ type: "auto"|"any"|"none" } 或 { type: "tool", name }。
temperaturenumber采样温度 0–1;启用 thinking 时须为 1。
top_pnumber核采样概率。
top_knumberTop-K 采样。
stop_sequencesstring[]停止词数组,命中即截断输出。
metadata{ user_id?: string }用于平台侧用户标识。
signalAbortSignal(第二个参数)传入 AbortController.signal 可取消请求。

gemini.generateContent()

client.gemini.generateContent(params, signal?)
参数类型必填说明
modelstring模型 ID,例如 gemini-3.1-pro-preview。
contentsContent[]对话内容,每项含 role("user"|"model")和 parts 数组。
streambooleantrue 返回 AsyncGenerator<GenerateContentResponse>,默认返回单次完整响应。
systemInstructionContent系统指令,格式同 contents,role 通常省略。
toolsGeminiTool[]工具定义,含 function_declarations 数组。
generationConfigGenerationConfig生成参数,见下表。
signalAbortSignal(第二个参数)传入 AbortController.signal 可取消请求。

GenerationConfig 字段

参数类型必填说明
temperaturenumber采样温度。
topPnumber核采样概率。
topKnumberTop-K 采样。
maxOutputTokensnumber最大输出 token 数。
stopSequencesstring[]停止词数组。
responseMimeTypestring输出 MIME 类型,例如 "application/json"。
candidateCountnumber候选回复数量,通常为 1。
thinkingConfigobject{ thinkingBudget?: number },启用思维链。

gemini.streamGenerateContent()

client.gemini.streamGenerateContent(params, signal?)
参数类型必填说明
modelstring模型 ID,会写入 /v1beta/models/{model}:streamGenerateContent 的 path。
contentsContent[]对话内容,每项含 role 和 parts 数组。
systemInstructionContent系统指令。
toolsGeminiTool[]工具定义。
generationConfigGenerationConfig生成参数。
signalAbortSignal(第二个参数)传入 AbortController.signal 可取消请求。

models

client.models.list(signal?)client.models.retrieve(model, signal?)
参数类型必填说明
modelstring仅 retrieve 必填;模型 ID,会写入 /v1/models/{model} 的 path。
signalAbortSignal传入 AbortController.signal 可取消请求。