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 互斥。

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

自定义主体令牌提供者

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

流式响应

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

import OpenAI from 'openai';

const client = new OpenAI();

const stream = await client.responses.create({
  model: 'gpt-5.2',
  input: '快说十遍“绵羊睡得很深”！',
  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 签名是 可选但推荐的。有关 Webhooks 的更多信息，请参阅 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();

实时 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: '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();
  // ...
}

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