名称: javascript-sdk 描述: “JavaScript/TypeScript SDK for inference.sh - 运行AI应用、构建智能代理、集成150+模型。包: @inferencesh/sdk (npm install)。完整的TypeScript支持、流式处理、文件上传。使用模板或即席模式构建代理，工具构建器API、技能、人工审批。用途: JavaScript集成、TypeScript、Node.js、React、Next.js、前端应用。触发词: javascript sdk、typescript sdk、npm install、node.js api、js客户端、react ai、next.js ai、前端sdk、@inferencesh/sdk、typescript代理、浏览器sdk、js集成” 允许工具: Bash(npm )、Bash(npx )、Bash(node )、Bash(pnpm )、Bash(yarn *)

JavaScript SDK

使用 inference.sh JavaScript/TypeScript SDK 构建AI应用程序。

JavaScript SDK

快速开始

npm install @inferencesh/sdk

import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

// 运行一个AI应用
const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A sunset over mountains' }
});
console.log(result.output);

安装

npm install @inferencesh/sdk
# 或
yarn add @inferencesh/sdk
# 或
pnpm add @inferencesh/sdk

要求: Node.js 18.0.0+ (或支持fetch的现代浏览器)

认证

import { inference } from '@inferencesh/sdk';

// 直接API密钥
const client = inference({ apiKey: 'inf_your_key' });

// 从环境变量 (推荐)
const client = inference({ apiKey: process.env.INFERENCE_API_KEY });

// 用于前端应用 (使用代理)
const client = inference({ proxyUrl: '/api/inference/proxy' });

获取您的API密钥: 设置 → API密钥 → 创建API密钥

运行应用

基本执行

const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A cat astronaut' }
});

console.log(result.status);  // "completed"
console.log(result.output);  // 输出数据

即发即忘

const task = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Drone flying over mountains' }
}, { wait: false });

console.log(`任务ID: ${task.id}`);
// 稍后使用 client.getTask(task.id) 检查

流式进度

const stream = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Ocean waves at sunset' }
}, { stream: true });

for await (const update of stream) {
  console.log(`状态: ${update.status}`);
  if (update.logs?.length) {
    console.log(update.logs.at(-1));
  }
}

运行参数

参数	类型	描述
`app`	字符串	应用ID (命名空间/名称@版本)
`input`	对象	输入匹配应用架构
`setup`	对象	隐藏设置配置
`infra`	字符串	‘cloud’ 或 ‘private’
`session`	字符串	用于有状态执行的会话ID
`session_timeout`	数字	空闲超时 (1-3600秒)

文件处理

自动上传

const result = await client.run({
  app: 'image-processor',
  input: {
    image: '/path/to/image.png'  // 自动上传
  }
});

手动上传

// 基本上传
const file = await client.uploadFile('/path/to/image.png');

// 带选项
const file = await client.uploadFile('/path/to/image.png', {
  filename: 'custom_name.png',
  contentType: 'image/png',
  public: true
});

const result = await client.run({
  app: 'image-processor',
  input: { image: file.uri }
});

浏览器文件上传

const input = document.querySelector('input[type="file"]');
const file = await client.uploadFile(input.files[0]);

会话 (有状态执行)

在多个调用间保持工作者温暖:

// 开始新会话
const result = await client.run({
  app: 'my-app',
  input: { action: 'init' },
  session: 'new',
  session_timeout: 300  // 5分钟
});
const sessionId = result.session_id;

// 在同一会话中继续
const result2 = await client.run({
  app: 'my-app',
  input: { action: 'process' },
  session: sessionId
});

代理SDK

模板代理

使用工作空间中的预构建代理:

const agent = client.agent('my-team/support-agent@latest');

// 发送消息
const response = await agent.sendMessage('Hello!');
console.log(response.text);

// 多轮对话
const response2 = await agent.sendMessage('Tell me more');

// 重置对话
agent.reset();

// 获取聊天历史
const chat = await agent.getChat();

即席代理

以编程方式创建自定义代理:

import { tool, string, number, appTool } from '@inferencesh/sdk';

// 定义工具
const calculator = tool('calculate')
  .describe('执行计算')
  .param('expression', string('数学表达式'))
  .build();

const imageGen = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('生成图像')
  .param('prompt', string('图像描述'))
  .build();

// 创建代理
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: '你是一个有帮助的助手。',
  tools: [calculator, imageGen],
  temperature: 0.7,
  max_tokens: 4096
});

const response = await agent.sendMessage('What is 25 * 4?');

可用核心应用

模型	应用引用
Claude Sonnet 4	`infsh/claude-sonnet-4@latest`
Claude 3.5 Haiku	`infsh/claude-haiku-35@latest`
GPT-4o	`infsh/gpt-4o@latest`
GPT-4o Mini	`infsh/gpt-4o-mini@latest`

工具构建器API

参数类型

import {
  string, number, integer, boolean,
  enumOf, array, obj, optional
} from '@inferencesh/sdk';

const name = string('用户名称');
const age = integer('年龄（岁）');
const score = number('分数0-1');
const active = boolean('是否激活');
const priority = enumOf(['low', 'medium', 'high'], '优先级');
const tags = array(string('标签'), '标签列表');
const address = obj({
  street: string('街道'),
  city: string('城市'),
  zip: optional(string('邮政编码'))
}, '地址');

客户端工具 (在代码中运行)

const greet = tool('greet')
  .display('问候用户')
  .describe('按名称问候用户')
  .param('name', string('要问候的名称'))
  .requireApproval()
  .build();

应用工具 (调用AI应用)

const generate = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('从文本生成图像')
  .param('prompt', string('图像描述'))
  .setup({ model: 'schnell' })
  .input({ steps: 20 })
  .requireApproval()
  .build();

代理工具 (委托给子代理)

import { agentTool } from '@inferencesh/sdk';

const researcher = agentTool('research', 'my-org/researcher@v1')
  .describe('研究主题')
  .param('topic', string('要研究的主题'))
  .build();

Webhook工具 (调用外部API)

import { webhookTool } from '@inferencesh/sdk';

const notify = webhookTool('slack', 'https://hooks.slack.com/...')
  .describe('发送Slack通知')
  .secret('SLACK_SECRET')
  .param('channel', string('频道'))
  .param('message', string('消息'))
  .build();

内部工具 (内置功能)

import { internalTools } from '@inferencesh/sdk';

const config = internalTools()
  .plan()
  .memory()
  .webSearch(true)
  .codeExecution(true)
  .imageGeneration({
    enabled: true,
    appRef: 'infsh/flux@latest'
  })
  .build();

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  internal_tools: config
});

流式代理响应

const response = await agent.sendMessage('解释量子计算', {
  onMessage: (msg) => {
    if (msg.content) {
      process.stdout.write(msg.content);
    }
  },
  onToolCall: async (call) => {
    console.log(`
[工具: ${call.name}]`);
    const result = await executeTool(call.name, call.args);
    agent.submitToolResult(call.id, result);
  }
});

文件附件

// 从文件路径 (Node.js)
import { readFileSync } from 'fs';
const response = await agent.sendMessage('这张图片里有什么？', {
  files: [readFileSync('image.png')]
});

// 从base64
const response = await agent.sendMessage('分析这个', {
  files: ['data:image/png;base64,iVBORw0KGgo...']
});

// 从浏览器File对象
const input = document.querySelector('input[type="file"]');
const response = await agent.sendMessage('描述这个', {
  files: [input.files[0]]
});

技能 (可重用上下文)

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  skills: [
    {
      name: 'code-review',
      description: '代码审查指南',
      content: '# 代码审查

1. 检查安全性
2. 检查性能...'
    },
    {
      name: 'api-docs',
      description: 'API文档',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});

服务器代理 (前端应用)

对于浏览器应用，通过后端代理以保持API密钥安全:

客户端设置

const client = inference({
  proxyUrl: '/api/inference/proxy'
  // 前端不需要apiKey
});

Next.js代理 (App Router)

// app/api/inference/proxy/route.ts
import { createRouteHandler } from '@inferencesh/sdk/proxy/nextjs';

const route = createRouteHandler({
  apiKey: process.env.INFERENCE_API_KEY
});

export const POST = route.POST;

Express代理

import express from 'express';
import { createProxyMiddleware } from '@inferencesh/sdk/proxy/express';

const app = express();
app.use('/api/inference/proxy', createProxyMiddleware({
  apiKey: process.env.INFERENCE_API_KEY
}));

支持框架

Next.js (App Router & Pages Router)
Express
Hono
Remix
SvelteKit

TypeScript支持

包含完整类型定义:

import type {
  TaskDTO,
  ChatDTO,
  ChatMessageDTO,
  AgentTool,
  TaskStatusCompleted,
  TaskStatusFailed
} from '@inferencesh/sdk';

if (result.status === TaskStatusCompleted) {
  console.log('完成!');
} else if (result.status === TaskStatusFailed) {
  console.log('失败:', result.error);
}

错误处理

import { RequirementsNotMetException, InferenceError } from '@inferencesh/sdk';

try {
  const result = await client.run({ app: 'my-app', input: {...} });
} catch (e) {
  if (e instanceof RequirementsNotMetException) {
    console.log('缺失要求:');
    for (const err of e.errors) {
      console.log(`  - ${err.type}: ${err.key}`);
    }
  } else if (e instanceof InferenceError) {
    console.log('API错误:', e.message);
  }
}

人工审批工作流

const response = await agent.sendMessage('删除所有临时文件', {
  onToolCall: async (call) => {
    if (call.requiresApproval) {
      const approved = await promptUser(`允许 ${call.name}?`);
      if (approved) {
        const result = await executeTool(call.name, call.args);
        agent.submitToolResult(call.id, result);
      } else {
        agent.submitToolResult(call.id, { error: '用户拒绝' });
      }
    }
  }
});

CommonJS支持

const { inference, tool, string } = require('@inferencesh/sdk');

const client = inference({ apiKey: 'inf_...' });
const result = await client.run({...});

参考文件

代理模式 - 多代理、RAG、批量处理模式
工具构建器 - 完整的工具构建器API参考
服务器代理 - Next.js、Express、Hono、Remix、SvelteKit设置
流式处理 - 实时进度更新和SSE处理
文件处理 - 上传、下载和管理文件
会话 - 有状态执行与温暖工作者
TypeScript - 类型定义和类型安全模式
React集成 - 钩子、组件和模式

文档

JavaScript SDK参考 - 完整API文档
代理SDK概述 - 构建代理
工具构建器参考 - 创建工具
服务器代理设置 - 前端集成
认证 - API密钥设置
流式处理 - 实时更新
文件上传 - 文件处理

JavaScript SDK

快速开始

安装

认证

运行应用

基本执行

即发即忘

流式进度

运行参数

文件处理

自动上传

手动上传

浏览器文件上传

会话 (有状态执行)

代理SDK

模板代理

即席代理

可用核心应用

工具构建器API

参数类型

客户端工具 (在代码中运行)

应用工具 (调用AI应用)

代理工具 (委托给子代理)

Webhook工具 (调用外部API)

内部工具 (内置功能)

流式代理响应

文件附件

技能 (可重用上下文)

服务器代理 (前端应用)

客户端设置

Next.js代理 (App Router)

Express代理

支持框架

TypeScript支持

错误处理

人工审批工作流

CommonJS支持

参考文件

相关技能

文档