javascript-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JavaScript SDK

Build AI applications with the inference.sh JavaScript/TypeScript SDK.

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

Quick Start

快速开始

bash

npm install @inferencesh/sdk

typescript

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

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

// Run an AI app
const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A sunset over mountains' }
});
console.log(result.output);

bash

npm install @inferencesh/sdk

typescript

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);

Installation

安装

bash

npm install @inferencesh/sdk

bash

npm install @inferencesh/sdk

or

或

yarn add @inferencesh/sdk

or

或

pnpm add @inferencesh/sdk


**Requirements:** Node.js 18.0.0+ (or modern browser with fetch)

pnpm add @inferencesh/sdk


**要求：** Node.js 18.0.0+（或支持fetch的现代浏览器）

Authentication

身份验证

typescript

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

// Direct API key
const client = inference({ apiKey: 'inf_your_key' });

// From environment variable (recommended)
const client = inference({ apiKey: process.env.INFERENCE_API_KEY });

// For frontend apps (use proxy)
const client = inference({ proxyUrl: '/api/inference/proxy' });

Get your API key: Settings → API Keys → Create API Key

typescript

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密钥

Running Apps

运行应用

Basic Execution

基础执行

typescript

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

console.log(result.status);  // "completed"
console.log(result.output);  // Output data

typescript

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

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

Fire and Forget

异步执行（无需等待结果）

typescript

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

console.log(`Task ID: ${task.id}`);
// Check later with client.getTask(task.id)

typescript

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)查询状态

Streaming Progress

流式进度更新

typescript

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(`Status: ${update.status}`);
  if (update.logs?.length) {
    console.log(update.logs.at(-1));
  }
}

typescript

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));
  }
}

Run Parameters

运行参数

Parameter	Type	Description
`app`	string	App ID (namespace/name@version)
`input`	object	Input matching app schema
`setup`	object	Hidden setup configuration
`infra`	string	'cloud' or 'private'
`session`	string	Session ID for stateful execution
`session_timeout`	number	Idle timeout (1-3600 seconds)

参数	类型	描述
`app`	string	应用ID（命名空间/名称@版本）
`input`	object	匹配应用 schema 的输入数据
`setup`	object	隐藏的配置参数
`infra`	string	'cloud'（云端）或 'private'（私有部署）
`session`	string	用于有状态执行的会话ID
`session_timeout`	number	空闲超时时间（1-3600秒）

File Handling

文件处理

Automatic Upload

自动上传

typescript

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

typescript

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

Manual Upload

手动上传

typescript

// Basic upload
const file = await client.uploadFile('/path/to/image.png');

// With options
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 }
});

typescript

// 基础上传
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 }
});

Browser File Upload

浏览器文件上传

typescript

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

typescript

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

Sessions (Stateful Execution)

会话（有状态执行）

Keep workers warm across multiple calls:

typescript

// Start new session
const result = await client.run({
  app: 'my-app',
  input: { action: 'init' },
  session: 'new',
  session_timeout: 300  // 5 minutes
});
const sessionId = result.session_id;

// Continue in same session
const result2 = await client.run({
  app: 'my-app',
  input: { action: 'process' },
  session: sessionId
});

在多次调用间保持工作进程活跃：

typescript

// 启动新会话
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
});

Agent SDK

Template Agents

模板Agent

Use pre-built agents from your workspace:

typescript

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

// Send message
const response = await agent.sendMessage('Hello!');
console.log(response.text);

// Multi-turn conversation
const response2 = await agent.sendMessage('Tell me more');

// Reset conversation
agent.reset();

// Get chat history
const chat = await agent.getChat();

使用工作区中的预构建Agent：

typescript

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();

Ad-hoc Agents

自定义Agent

Create custom agents programmatically:

typescript

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

// Define tools
const calculator = tool('calculate')
  .describe('Perform a calculation')
  .param('expression', string('Math expression'))
  .build();

const imageGen = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image')
  .param('prompt', string('Image description'))
  .build();

// Create agent
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful assistant.',
  tools: [calculator, imageGen],
  temperature: 0.7,
  max_tokens: 4096
});

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

通过代码创建自定义Agent：

typescript

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

// 定义工具
const calculator = tool('calculate')
  .describe('Perform a calculation')
  .param('expression', string('Math expression'))
  .build();

const imageGen = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image')
  .param('prompt', string('Image description'))
  .build();

// 创建Agent
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful assistant.',
  tools: [calculator, imageGen],
  temperature: 0.7,
  max_tokens: 4096
});

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

Available Core Apps

可用核心应用

Model	App Reference
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`

模型	应用引用
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`

Tool Builder API

工具构建器API

Parameter Types

参数类型

typescript

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

const name = string('User\'s name');
const age = integer('Age in years');
const score = number('Score 0-1');
const active = boolean('Is active');
const priority = enumOf(['low', 'medium', 'high'], 'Priority');
const tags = array(string('Tag'), 'List of tags');
const address = obj({
  street: string('Street'),
  city: string('City'),
  zip: optional(string('ZIP'))
}, 'Address');

typescript

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

const name = string('User\'s name');
const age = integer('Age in years');
const score = number('Score 0-1');
const active = boolean('Is active');
const priority = enumOf(['low', 'medium', 'high'], 'Priority');
const tags = array(string('Tag'), 'List of tags');
const address = obj({
  street: string('Street'),
  city: string('City'),
  zip: optional(string('ZIP'))
}, 'Address');

Client Tools (Run in Your Code)

客户端工具（在你的代码中运行）

typescript

const greet = tool('greet')
  .display('Greet User')
  .describe('Greets a user by name')
  .param('name', string('Name to greet'))
  .requireApproval()
  .build();

typescript

const greet = tool('greet')
  .display('Greet User')
  .describe('Greets a user by name')
  .param('name', string('Name to greet'))
  .requireApproval()
  .build();

App Tools (Call AI Apps)

应用工具（调用AI应用）

typescript

const generate = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image from text')
  .param('prompt', string('Image description'))
  .setup({ model: 'schnell' })
  .input({ steps: 20 })
  .requireApproval()
  .build();

typescript

const generate = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image from text')
  .param('prompt', string('Image description'))
  .setup({ model: 'schnell' })
  .input({ steps: 20 })
  .requireApproval()
  .build();

Agent Tools (Delegate to Sub-agents)

Agent工具（委托给子Agent）

typescript

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

const researcher = agentTool('research', 'my-org/researcher@v1')
  .describe('Research a topic')
  .param('topic', string('Topic to research'))
  .build();

typescript

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

const researcher = agentTool('research', 'my-org/researcher@v1')
  .describe('Research a topic')
  .param('topic', string('Topic to research'))
  .build();

Webhook Tools (Call External APIs)

Webhook工具（调用外部API）

typescript

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

const notify = webhookTool('slack', 'https://hooks.slack.com/...')
  .describe('Send Slack notification')
  .secret('SLACK_SECRET')
  .param('channel', string('Channel'))
  .param('message', string('Message'))
  .build();

typescript

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

const notify = webhookTool('slack', 'https://hooks.slack.com/...')
  .describe('Send Slack notification')
  .secret('SLACK_SECRET')
  .param('channel', string('Channel'))
  .param('message', string('Message'))
  .build();

Internal Tools (Built-in Capabilities)

内置工具（原生功能）

typescript

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
});

typescript

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
});

Streaming Agent Responses

Agent响应流式传输

typescript

const response = await agent.sendMessage('Explain quantum computing', {
  onMessage: (msg) => {
    if (msg.content) {
      process.stdout.write(msg.content);
    }
  },
  onToolCall: async (call) => {
    console.log(`\n[Tool: ${call.name}]`);
    const result = await executeTool(call.name, call.args);
    agent.submitToolResult(call.id, result);
  }
});

typescript

const response = await agent.sendMessage('Explain quantum computing', {
  onMessage: (msg) => {
    if (msg.content) {
      process.stdout.write(msg.content);
    }
  },
  onToolCall: async (call) => {
    console.log(`\n[工具: ${call.name}]`);
    const result = await executeTool(call.name, call.args);
    agent.submitToolResult(call.id, result);
  }
});

File Attachments

文件附件

typescript

// From file path (Node.js)
import { readFileSync } from 'fs';
const response = await agent.sendMessage('What\'s in this image?', {
  files: [readFileSync('image.png')]
});

// From base64
const response = await agent.sendMessage('Analyze this', {
  files: ['data:image/png;base64,iVBORw0KGgo...']
});

// From browser File object
const input = document.querySelector('input[type="file"]');
const response = await agent.sendMessage('Describe this', {
  files: [input.files[0]]
});

typescript

// 从文件路径（Node.js）
import { readFileSync } from 'fs';
const response = await agent.sendMessage('What\'s in this image?', {
  files: [readFileSync('image.png')]
});

// 从base64编码
const response = await agent.sendMessage('Analyze this', {
  files: ['data:image/png;base64,iVBORw0KGgo...']
});

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

Skills (Reusable Context)

Skills（可复用上下文）

typescript

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  skills: [
    {
      name: 'code-review',
      description: 'Code review guidelines',
      content: '# Code Review\n\n1. Check security\n2. Check performance...'
    },
    {
      name: 'api-docs',
      description: 'API documentation',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});

typescript

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  skills: [
    {
      name: 'code-review',
      description: 'Code review guidelines',
      content: '# Code Review\n\n1. Check security\n2. Check performance...'
    },
    {
      name: 'api-docs',
      description: 'API documentation',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});

Server Proxy (Frontend Apps)

服务器代理（前端应用）

For browser apps, proxy through your backend to keep API keys secure:

对于浏览器应用，通过后端代理以保护API密钥：

Client Setup

客户端配置

typescript

const client = inference({
  proxyUrl: '/api/inference/proxy'
  // No apiKey needed on frontend
});

typescript

const client = inference({
  proxyUrl: '/api/inference/proxy'
  // 前端无需配置apiKey
});

Next.js Proxy (App Router)

Next.js代理（App Router）

typescript

// 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;

typescript

// 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 Proxy

Express代理

typescript

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
}));

typescript

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
}));

Supported Frameworks

支持的框架

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

Next.js（App Router & Pages Router）
Express
Hono
Remix
SvelteKit

TypeScript Support

TypeScript支持

Full type definitions included:

typescript

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

if (result.status === TaskStatusCompleted) {
  console.log('Done!');
} else if (result.status === TaskStatusFailed) {
  console.log('Failed:', result.error);
}

包含完整的类型定义：

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);
}

Error Handling

错误处理

typescript

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

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

typescript

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);
  }
}

Human Approval Workflows

人工审批工作流

typescript

const response = await agent.sendMessage('Delete all temp files', {
  onToolCall: async (call) => {
    if (call.requiresApproval) {
      const approved = await promptUser(`Allow ${call.name}?`);
      if (approved) {
        const result = await executeTool(call.name, call.args);
        agent.submitToolResult(call.id, result);
      } else {
        agent.submitToolResult(call.id, { error: 'Denied by user' });
      }
    }
  }
});

typescript

const response = await agent.sendMessage('Delete all temp files', {
  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 Support

CommonJS支持

javascript

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

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

javascript

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

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

Reference Files

参考文档

Agent Patterns - Multi-agent, RAG, batch processing patterns
Tool Builder - Complete tool builder API reference
Server Proxy - Next.js, Express, Hono, Remix, SvelteKit setup
Streaming - Real-time progress updates and SSE handling
File Handling - Upload, download, and manage files
Sessions - Stateful execution with warm workers
TypeScript - Type definitions and type-safe patterns
React Integration - Hooks, components, and patterns

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

Related Skills

Python SDK

npx skills add inference-sh/skills@python-sdk

Full platform skill (all 150+ apps via CLI)

全平台Skill（通过CLI访问150+应用）

npx skills add inference-sh/skills@inference-sh

LLM models

LLM模型

npx skills add inference-sh/skills@llm-models

Image generation

图像生成

npx skills add inference-sh/skills@ai-image-generation

undefined

npx skills add inference-sh/skills@ai-image-generation

undefined

Documentation

官方文档

JavaScript SDK Reference - Full API documentation
Agent SDK Overview - Building agents
Tool Builder Reference - Creating tools
Server Proxy Setup - Frontend integration
Authentication - API key setup
Streaming - Real-time updates
File Uploads - File handling

JavaScript SDK参考 - 完整API文档
Agent SDK概览 - Agent构建指南
工具构建器参考 - 工具创建指南
服务器代理配置 - 前端集成指南
身份验证 - API密钥配置
流式处理 - 实时更新
文件上传 - 文件处理