TypeScript SDK
@hypershub/sdk — El cliente oficial TypeScript/Node.js, compatible con Chat Completions, Responses, Anthropic Messages y Models. Compatible con Node.js ≥ 18 y navegadores modernos.
Instalación
npm install @hypershub/sdkConfiguración
Crea una instancia de HypersHub. Se recomienda pasar la API Key mediante variables de entorno para evitar incrustarla en el código fuente.
import { HypersHub } from '@hypershub/sdk'
// 从环境变量自动读取 HYPERSHUB_API_KEY
const client = new HypersHub()
// 或显式传入
const client = new HypersHub({
apiKey: 'sk-hy-...',
baseURL: 'https://apiclaw.cc', // 可选,默认值
})| Parámetro | Tipo | Descripción |
|---|---|---|
| apiKey | string | API Key de la plataforma, por defecto lee la variable de entorno HYPERSHUB_API_KEY |
| baseURL | string | URL base de la API, por defecto https://apiclaw.cc |
| defaultHeaders | Record<string, string> | Cabeceras personalizadas adjuntas a cada solicitud |
Chat Completions
Totalmente compatible con la API de Chat de OpenAI, compatible con todos los modelos, incluidos Claude, GPT y 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
Llama a la API estilo OpenAI Responses, adecuada para nueva generación de texto, salida estructurada y orquestación de respuestas de múltiples turnos.
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
Llama a modelos Claude mediante la API nativa de Anthropic Messages, con soporte para Extended Thinking y conversaciones de múltiples turnos.
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)Models
Consulta la lista de modelos disponibles u obtén los detalles de un modelo por su ID en la ruta.
const models = await client.models.list()
for (const model of models.data) {
console.log(model.id)
}Errores
Todos los errores de la API lanzan errores tipados que extienden HypersHubError, y pueden manejarse con precisión mediante el campo 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
}
}| Clase de error | Código HTTP | Causa |
|---|---|---|
| HypersHubAuthError | 401 | API Key inválida o expirada |
| HypersHubInsufficientBalanceError | 402 | Saldo de cuenta insuficiente |
| HypersHubRateLimitError | 429 | Límite de frecuencia o concurrencia de solicitudes excedido |
| HypersHubError | Otros 4xx / 5xx | Clase base de error general de API |
Cancelación de solicitud
Todos los métodos aceptan AbortSignal como segundo argumento, útil para timeouts o cancelación por parte del usuario.
// 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
Documentación completa de parámetros y valores de retorno para todos los métodos públicos.
chat.completions.create()
client.chat.completions.create(params, signal?)| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model | string | ✓ | ID del modelo, ej. claude-sonnet-4-6, gpt-5.4, gemini-3.1-pro-preview. |
| messages | ChatMessage[] | ✓ | Historial de conversación, compatible con roles system / developer / user / assistant / tool. |
| stream | boolean | — | true devuelve AsyncGenerator<ChatCompletionChunk>, false (por defecto) devuelve ChatCompletion. |
| tools | Tool[] | — | Definiciones de herramientas Function Calling, type fijado a "function". |
| tool_choice | string | object | — | "auto", "any", "none" o especifica un nombre de herramienta. |
| reasoning_effort | "low"|"medium"|"high" | — | Esfuerzo de razonamiento, solo compatible con algunos modelos. |
| temperature | number | — | Temperatura de muestreo, rango 0–2; fijada a 1 para modelos de razonamiento. |
| top_p | number | — | Probabilidad de muestreo de núcleo, rango 0–1. |
| presence_penalty | number | — | Penalización de presencia, rango -2 a 2. |
| frequency_penalty | number | — | Penalización de frecuencia, rango -2 a 2. |
| max_completion_tokens | number | — | Máximo de tokens de salida; se recomienda usar este campo. |
| max_tokens | number | — | Campo heredado, el gateway convierte automáticamente a max_completion_tokens. |
| response_format | object | — | "text" o "json_object", especifica el formato de salida. |
| stop | string | string[] | — | Secuencias de parada; la salida se trunca al coincidir. |
| user | string | — | Identificador de usuario final, usado para monitoreo en la plataforma. |
| signal | AbortSignal | — | (Segundo argumento) Pasa AbortController.signal para cancelar la solicitud. |
responses.create()
client.responses.create(params, signal?)| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model | string | ✓ | ID del modelo, ej. gpt-5.4, claude-sonnet-4-6. |
| input | string | array | ✓ | Texto de entrada o array de mensajes. |
| stream | boolean | — | true devuelve AsyncGenerator<ResponseStreamEvent>, por defecto devuelve ModelResponse. |
| instructions | string | — | Instrucciones a nivel de sistema. |
| max_output_tokens | number | — | Máximo de tokens de salida. |
| reasoning_effort | "low"|"medium"|"high" | — | Esfuerzo de razonamiento, solo compatible con algunos modelos. |
| temperature | number | — | Temperatura de muestreo. |
| tools | Tool[] | object[] | — | Definiciones de herramientas. |
| text | object | — | Configuración de formato de salida de texto, compatible con text / json_object / json_schema. |
| previous_response_id | string | — | ID de respuesta anterior, usado para continuación de múltiples turnos. |
| signal | AbortSignal | — | (Segundo argumento) Pasa AbortController.signal para cancelar la solicitud. |
messages.create()
client.messages.create(params, signal?)| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model | string | ✓ | ID del modelo Claude, ej. claude-opus-4-8, claude-sonnet-4-6. |
| messages | MessageParam[] | ✓ | Array de mensajes, el valor de role es "user" o "assistant". |
| max_tokens | number | ✓ | Máximo de tokens de salida. |
| system | string | object[] | — | Cadena de prompt del sistema, o array de bloques [{ type: "text", text }]. |
| stream | boolean | — | true devuelve AsyncGenerator<MessageStreamEvent>. |
| thinking | object | — | boolean o { type: "enabled", budget_tokens: number }. |
| tools | AnthropicTool[] | — | Definiciones de herramientas, incluyendo name, description, input_schema. |
| tool_choice | object | — | "auto", "any", "none" o especifica un nombre de herramienta. |
| temperature | number | — | Temperatura de muestreo 0–1; debe ser 1 cuando thinking está habilitado. |
| top_p | number | — | Probabilidad de muestreo de núcleo. |
| top_k | number | — | Muestreo Top-K. |
| stop_sequences | string[] | — | Array de secuencias de parada; la salida se trunca al coincidir. |
| metadata | { user_id?: string } | — | Usado para identificación de usuario en la plataforma. |
| signal | AbortSignal | — | (Segundo argumento) Pasa AbortController.signal para cancelar la solicitud. |
models
client.models.list(signal?)client.models.retrieve(model, signal?)| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| model | string | ✓ | Solo requerido para retrieve; el ID del modelo se escribe en /v1/models/model. |
| signal | AbortSignal | — | Pasa AbortController.signal para cancelar la solicitud. |

