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: 'You are a coding assistant that talks like a pirate',
  input: 'Are semicolons optional in JavaScript?',
});

console.log(response.output_text);

此前生成文本的标准 API（将无限期支持）是 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: 'Talk like a pirate.' },
    { role: 'user', content: 'Are semicolons optional in JavaScript?' },
  ],
});

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

Workload Identity 身份验证

对于云托管 Kubernetes、Azure 和 GCP 等安全自动化环境，您可以使用来自云身份提供商的短期令牌进行 Workload Identity 身份验证，以替代长期有效的 API 密钥。workloadIdentity 参数与 apiKey 互斥。

Kubernetes（服务账户令牌）

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

const client = new OpenAI({
  workloadIdentity: {
    clientId: 'your-client-id',
    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: 'Hello!' }],
});

Azure（托管标识）

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

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

GCP（计算引擎元数据）

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

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

自定义 Subject Token 提供者

import OpenAI from 'openai';

const client = new OpenAI({
  workloadIdentity: {
    clientId: 'your-client-id',
    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: {
    clientId: 'your-client-id',
    identityProviderId: 'idp-123',
    serviceAccountId: 'sa-456',
    provider: k8sServiceAccountTokenProvider('/var/token'),
    refreshBufferSeconds: 120.0,
  },
});

流式响应

我们提供使用 Server-Sent Events (SSE) 支持流式响应。

import OpenAI from 'openai';

const client = new OpenAI();

const stream = await client.responses.create({
  model: 'gpt-5.2',
  input: 'Say "Sheep sleep deep" ten times fast!',
  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('Response completed:', event.data);
        break;
      case 'response.failed':
        console.log('Response failed:', event.data);
        break;
      default:
        console.log('Unhandled event type:', event.type);
    }

    return Response.json({ message: 'ok' });
  } catch (error) {
    console.error('Invalid webhook signature:', error);
    return new Response('Invalid signature', { status: 400 });
  }
}

直接验证 Webhook 载荷

在某些情况下，您可能希望将 webhook 验证与载荷解析分开处理。如果您倾向于分别处理这些步骤，我们提供了 client.webhooks.verifySignature() 方法来_仅验证_ webhook 请求的签名。与 .unwrap() 类似，如果签名无效，此方法也会抛出错误。注意，body 参数必须是服务器发送的原始 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 {
    client.webhooks.verifySignature(body, headersList);
    
    // 验证签名后解析载荷
    const event = JSON.parse(body);
    console.log('Verified event:', event);
    
    return Response.json({ message: 'ok' });
  } catch (error) {
    console.error('Invalid webhook signature:', 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: 'Say this is a test' }],
  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: 'Say this is a test' }],
    stream: true,
  })
  .withResponse();

Realtime API

Realtime 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: 'Say hello!' }],
});

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: 'How can I get the name of the current day in 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: 'How can I list all files in a directory using 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: 'testing 123',
});

console.log(response._request_id); // req_123

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

const { data: stream, request_id } = await openai.responses
  .create({
    model: 'gpt-5.2',
    input: 'Say this is a test',
    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();
  // ...
}

Realtime API

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