跳转到主要内容

​
使用 Node.js SDK 运行

当你想从 Node.js 或 TypeScript 调用工作流部署时，请使用官方的 @fetch-hive/sdk 包。SDK 包装了公共的 POST /v1/workflow/invoke 端点，处理身份验证，并同时支持直接响应和回调投递。

​
安装

npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
该 SDK 针对 Node.js 18+（使用全局 fetch），并附带 TypeScript 类型定义。

​
身份验证

将 FETCH_HIVE_API_KEY 环境变量设置为你的工作区 API 密钥： 
export FETCH_HIVE_API_KEY=fhk_...

import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
或显式传入密钥： 
const client = new FetchHive({ apiKey: 'fhk_...' });
有关如何创建和轮换密钥，请参阅 API 密钥。

​
基本示例

直接运行工作流部署。该调用会阻塞，直到工作流完成： 
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
});

console.log(run.status);
console.log(run.output);
请参阅 直接响应结构。

​
方法参考

字段类型必填描述
deploymentstring是工作流部署名称
variantstring否部署变体名称
inputsRecord<string, unknown>否Start 步骤定义的变量的键值对
async{ enabled: boolean, callback_url?: string }否回调投递设置
userstring否在 用户跟踪 中显示的不透明调用方标识符
metadataRecord<string, string | number | boolean | null>否调用方定义的扁平元数据，用于审计和日志过滤。请参阅 调用元数据

​
处理响应

const run = await client.invokeWorkflow({
  deployment: 'my-workflow',
  variant: 'default',
});

console.log(run.status);       // "completed" | "failed" | "running" | "queued"
console.log(run.output);       // final workflow output
console.log(run.request_id);   // use this to look up the run in Logs

​
回调投递

传入一个 async 块以立即返回，并让 Fetch Hive 在运行完成时调用你的回调 URL： 
const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
  async: { enabled: true, callback_url: 'https://example.com/callback' },
});

console.log('Queued:', run.status);
console.log('Webhook secret:', run.webhook_secret);
请保存 webhook_secret，以便你能验证传入回调的签名。请参阅 回调投递与 Webhook 触发 了解验证流程和签名负载结构。

​
配置

选项默认值描述
apiKeyprocess.env.FETCH_HIVE_API_KEY来自仪表板的 Bearer 令牌
baseURLhttps://api.fetchhive.com/v1覆盖 API 基础 URL
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
对于长时间运行的直接工作流请求，请优先使用 async: { enabled: true, ... }，而不是增加客户端超时时间。

​
错误

非 2xx 响应会抛出一个 Error，其消息包含状态码和响应体： 
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
有关工作流特有的失败案例，请参阅 错误处理；有关 HTTP 状态码含义，请参阅 错误与速率限制。

​
链接

​
后续步骤