openai/openai-node 源代码：https://github.com/openai/openai-node

OpenAI TypeScript 和 JavaScript API 库

npm 包大小 JSR 版本 (https://jsr.io/@openai/openai)

本库提供了从 TypeScript 或 JavaScript 便捷访问 OpenAI REST API 的能力。它根据我们的 OpenAPI 规范 (https://github.com/openai/openai-openapi) 并使用 Stainless (https://stainlessapi.com/) 生成。

要了解如何使用 OpenAI API，请查阅我们的 API 参考 (https://platform.openai.com/docs/api-reference) 和文档 (https://platform.openai.com/docs)。

安装

npm install openai

从 JSR 安装

deno add jsr:@openai/openai
npx jsr add @openai/openai

这些命令将使模块可从 @openai/openai 作用域导入。如果你使用 Deno JavaScript 运行时，还可以直接通过 JSR (https://jsr.io/docs/using-packages#importing-with-jsr-specifiers) 导入，无需安装步骤：

import OpenAI from 'jsr:@openai/openai';

用法

本库的完整 API 可在 api.md 文件 以及众多代码示例 (https://github.com/openai/openai-node/tree/master/examples) 中找到。

与 OpenAI 模型交互的主要 API 是 Responses API (https://platform.openai.com/docs/api-reference/responses)。你可以使用以下代码从模型生成文本：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // 这是默认值，可以省略
});

const response = await client.responses.create({
  model: 'gpt-5.2',
  instructions: '你是一个像海盗一样说话的编程助手',
  input: 'JavaScript 中分号是可选的么？',
});

console.log(response.output_text);

之前的标准（长期支持）是 Chat Completions API (https://platform.openai.com/docs/api-reference/chat)。你可以使用以下代码通过该 API 从模型生成文本：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // 这是默认值，可以省略
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.2',
  messages: [
    { role: 'developer', content: '像海盗一样说话。' },
    { role: 'user', content: 'JavaScript 中分号是可选的么？' },
  ],
});

console.log(completion.choices[0].message.content);

工作负载身份认证

对于安全的自动化环境（如云托管的 Kubernetes、Azure 和 GCP），你可以使用工作负载身份认证，采用云身份提供商的短期令牌，而非长期 API 密钥。workloadIdentity 参数与 apiKey 互斥。必填字段为 identityProviderId、serviceAccountId 和 provider。

Kubernetes（服务账户令牌）

import OpenAI from 'openai';
import { k8sServiceAccountTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: k8sServiceAccountTokenProvider('/var/run/secrets/kubernetes.io/serviceaccount/token'),
  },
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: '你好！' }],
});

Azure（托管标识）

import OpenAI from 'openai';
import { azureManagedIdentityTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: azureManagedIdentityTokenProvider(),
  },
});

GCP（计算引擎元数据）

import OpenAI from 'openai';
import { gcpIDTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: gcpIDTokenProvider(),
  },
});

自定义主题令牌提供者

import OpenAI from 'openai';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: {
      tokenType: 'jwt',
      getToken: async () => {
        return 'your-jwt-token';
      },
    },
  },
});

你还可以自定义令牌刷新的缓冲时间（默认在过期前 1200 秒（20 分钟））：

import OpenAI from 'openai';
import { k8sServiceAccountTokenProvider } from 'openai/auth';

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: k8sServiceAccountTokenProvider('/var/token'),
    refreshBufferSeconds: 120.0,
  },
});

流式响应

我们支持使用服务器发送事件（SSE）进行流式响应。

import OpenAI from 'openai';

const client = new OpenAI();

const stream = await client.responses.create({
  model: 'gpt-5.2',
  input: '快速重复说十遍 "Sheep sleep deep"！',
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

文件上传

对应于文件上传的请求参数可以以多种形式传递：

• File（或具有相同结构的对象）
• fetch 的 Response（或具有相同结构的对象）
• fs.ReadStream
• 我们的 toFile 帮助函数的返回值

import fs from 'fs';
import OpenAI, { toFile } from 'openai';

const client = new OpenAI();

// 如果你能访问 Node `fs`，推荐使用 `fs.createReadStream()`：
await client.files.create({
  file: fs.createReadStream('input.jsonl'),
  purpose: 'fine-tune',
});

// 或者如果你有 Web `File` API，可以传递一个 `File` 实例：
await client.files.create({
  file: new File(['my bytes'], 'input.jsonl'),
  purpose: 'fine-tune',
});

// 你也可以传递一个 `fetch` 的 `Response`：
await client.files.create({
  file: await fetch('https://somesite/input.jsonl'),
  purpose: 'fine-tune',
});

// 最后，如果以上都不方便，你可以使用我们的 `toFile` 帮助函数：
await client.files.create({
  file: await toFile(Buffer.from('my bytes'), 'input.jsonl'),
  purpose: 'fine-tune',
});

await client.files.create({
  file: await toFile(new Uint8Array([0, 1, 2]), 'input.jsonl'),
  purpose: 'fine-tune',
});

Webhook 验证

验证 webhook 签名是可选的但推荐。有关 webhook 的更多信息，请参见 API 文档 (https://platform.openai.com/docs/guides/webhooks)。

解析 webhook 负载

对于大多数用例，你可能希望同时验证 webhook 并解析负载。为此，我们提供了方法 client.webhooks.unwrap()，它解析一个 webhook 请求并验证它是由 OpenAI 发送的。如果签名无效，此方法将抛出错误。请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要事先解析它）。.unwrap() 方法将在验证 webhook 来自 OpenAI 后，为你将此 JSON 解析为一个事件对象。

import { headers } from 'next/headers';
import OpenAI from 'openai';

const client = new OpenAI({
  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // 默认使用环境变量；此处显式指定。
});

export async function webhook(request: Request) {
  const headersList = headers();
  const body = await request.text();
  try {
    const event = client.webhooks.unwrap(body, headersList);
    switch (event.type) {
      case 'response.completed':
        console.log('响应完成:', event.data);
        break;
      case 'response.failed':
        console.log('响应失败:', event.data);
        break;
      default:
        console.log('未处理的事件类型:', event.type);
    }
    return Response.json({ message: 'ok' });
  } catch (error) {
    console.error('无效的 webhook 签名:', error);
    return new Response('Invalid signature', { status: 400 });
  }
}

直接验证 webhook 负载

在某些情况下，你可能希望将验证 webhook 与解析负载分开处理。如果你更喜欢分别处理这些步骤，我们提供了方法 client.webhooks.verifySignature() 来仅验证 webhook 请求的签名。与 .unwrap() 一样，如果签名无效，此方法将抛出错误。请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要事先解析它）。然后在验证签名后，你需要解析 body。

import { headers } from 'next/headers';
import OpenAI from 'openai';

const client = new OpenAI({
  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // 默认使用环境变量；此处显式指定。
});

export async function webhook(request: Request) {
  const headersList = headers();
  const body = await request.text();
  try {
    client.webhooks.verifySignature(body, headersList);
    // 验证后解析 body
    const event = JSON.parse(body);
    console.log('已验证的事件:', event);
    return Response.json({ message: 'ok' });
  } catch (error) {
    console.error('无效的 webhook 签名:', error);
    return new Response('Invalid signature', { status: 400 });
  }
}

错误处理

当库无法连接到 API，或者 API 返回非成功状态码（即 4xx 或 5xx 响应）时，将抛出 APIError 的子类：

const job = await client.fineTuning.jobs
  .create({ model: 'gpt-4o', training_file: 'file-abc123' })
  .catch(async (err) => {
    if (err instanceof OpenAI.APIError) {
      console.log(err.request_id);
      console.log(err.status);    // 400
      console.log(err.name);      // BadRequestError
      console.log(err.headers);   // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

错误码如下：

请求 ID

关于调试请求的更多信息，请参阅这些文档 (https://platform.openai.com/docs/api-reference/debugging-requests)

SDK 中所有对象响应都提供了一个 _request_id 属性，该属性来自 x-request-id 响应头，以便你可以快速记录失败的请求并将其报告给 OpenAI。

const completion = await client.chat.completions.create({
  messages: [{ role: 'user', content: '说这是个测试' }],
  model: 'gpt-5.2',
});
console.log(completion._request_id); // req_123

你还可以使用 .withResponse() 方法访问请求 ID：

const { data: stream, request_id } = await openai.chat.completions
  .create({
    model: 'gpt-5.2',
    messages: [{ role: 'user', content: '说这是个测试' }],
    stream: true,
  })
  .withResponse();

实时 API

实时 API 使你能够构建低延迟、多模态的对话体验。目前支持文本和音频作为输入和输出，以及通过 WebSocket 连接进行函数调用 (https://platform.openai.com/docs/guides/function-calling)。

import { OpenAIRealtimeWebSocket } from 'openai/realtime/websocket';

const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-realtime' });

rt.on('response.text.delta', (event) => process.stdout.write(event.delta));

更多信息请参见 realtime.md。

Microsoft Azure OpenAI

要将此库与 Azure OpenAI (https://learn.microsoft.com/azure/ai-services/openai/overview) 一起使用，请使用 AzureOpenAI 类而不是 OpenAI 类。

[!重要] Azure API 的形状与核心 API 形状略有不同，这意味着响应/参数的静态类型不会总是正确的。

import { AzureOpenAI } from 'openai';
import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';

const credential = new DefaultAzureCredential();
const scope = 'https://cognitiveservices.azure.com/.default';
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const openai = new AzureOpenAI({ azureADTokenProvider });

const result = await openai.chat.completions.create({
  model: 'gpt-5.2',
  messages: [{ role: 'user', content: '你好！' }],
});

console.log(result.choices[0]!.message?.content);

重试

某些错误默认会自动重试 2 次，使用短指数退避。连接错误（例如由于网络连接问题）、408 请求超时、409 冲突、429 速率限制和 >=500 内部错误默认都会被重试。你可以使用 maxRetries 选项进行配置或禁用：

// 为所有请求配置默认值：
const client = new OpenAI({ maxRetries: 0 }); // 默认是 2

// 或者针对单个请求进行配置：
await client.chat.completions.create(
  {
    messages: [{ role: 'user', content: '如何获取 JavaScript 中当前日期的名称？' }],
    model: 'gpt-5.2',
  },
  { maxRetries: 5 }
);

超时

请求默认在 10 分钟后超时。你可以使用 timeout 选项进行配置：

// 为所有请求配置默认值：
const client = new OpenAI({ timeout: 20 * 1000 }); // 20 秒（默认是 10 分钟）

// 每个请求单独设置：
await client.chat.completions.create(
  {
    messages: [{ role: 'user', content: '如何使用 Python 列出目录中的所有文件？' }],
    model: 'gpt-5.2',
  },
  { timeout: 5 * 1000 }
);

超时时，将抛出 APIConnectionTimeoutError。请注意，超时的请求默认会被重试两次。

请求 ID

关于调试请求的更多信息，请参阅这些文档 (https://platform.openai.com/docs/api-reference/debugging-requests)

SDK 中所有对象响应都提供了一个 _request_id 属性，该属性来自 x-request-id 响应头，以便你可以快速记录失败的请求并将其报告给 OpenAI。

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: '测试 123'
});
console.log(response._request_id); // req_123

你还可以使用 .withResponse() 方法访问请求 ID：

const { data: stream, request_id } = await openai.responses
  .create({
    model: 'gpt-5.2',
    input: '说这是个测试',
    stream: true,
  })
  .withResponse();

自动分页

OpenAI API 中的列表方法都是分页的。你可以使用 for await ... of 语法在所有页面上迭代：

async function fetchAllFineTuningJobs(params) {
  const allFineTuningJobs = [];
  // 根据需要自动获取更多页面。
  for await (const fineTuningJob of client.fineTuning.jobs.list({ limit: 20 })) {
    allFineTuningJobs.push(fineTuningJob);
  }
  return allFineTuningJobs;
}

或者，你也可以一次请求单个页面：

let page = await client.fineTuning.jobs.list({ limit: 20 });
for (const fineTuningJob of page.data) {
  console.log(fineTuningJob);
}
// 提供了手动分页的便捷方法：
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

实时 API

实时 API 使你能够构建低延迟、多模态的对话体验。目前支持文本和音频作为输入和输出，以及通过 WebSocket 连接进行函数调用 (https://platform.openai.com/docs/guides/function-calling)。

import { OpenAIRealtimeWebSocket } from 'openai/realtime/websocket';

const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-realtime' });

rt.on('response.text.delta', (event) => process.stdout.write(event.delta));

更多信息请参见 realtime.md。

Microsoft Azure OpenAI

要将此库与 Azure OpenAI (https://learn.microsoft.com/azure/ai-services/openai/overview) 一起使用，请使用 AzureOpenAI 类而不是 OpenAI 类。

[!重要] Azure API 的形状与核心 API 形状略有不同，这意味着响应/参数的静态类型不会总是正确的。

import { AzureOpenAI } from 'openai';
import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';

const credential = new DefaultAzureCredential();
const scope = 'https://cognitiveservices.azure.com/.default';
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const openai = new AzureOpenAI({ azureADTokenProvider, ap