OpenAI TypeScript 和 JavaScript API 库

该库提供了从 TypeScript 或 JavaScript 便捷访问 OpenAI REST API 的功能。

它是由我们的 OpenAPI 规范 使用 Stainless 生成的。

要了解如何使用 OpenAI API，请查看我们的 API 参考 和 文档。

安装

npm install openai

从 JSR 安装

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

这些命令将使模块可以从 @openai/openai 范围导入。如果您使用的是 Deno JavaScript 运行时，也可以 直接从 JSR 导入，而无需安装步骤：

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

用法

本库的完整 API 可在 api.md 文件 中找到，此外还有大量 代码示例。

与 OpenAI 模型交互的主要 API 是 Responses API。您可以使用以下代码从模型生成文本。

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

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

之前用于生成文本的标准（无限期支持）是 Chat Completions API。您可以使用以下代码通过该 API 从模型生成文本。

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

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

流式响应

我们提供使用服务器发送事件 (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();

// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
await client.files.create({ file: fs.createReadStream('input.jsonl'), purpose: 'fine-tune' });

// Or if you have the web `File` API you can pass a `File` instance:
await client.files.create({ file: new File(['my bytes'], 'input.jsonl'), purpose: 'fine-tune' });

// You can also pass a `fetch` `Response`:
await client.files.create({
  file: await fetch('https://somesite/input.jsonl'),
  purpose: 'fine-tune',
});

// Finally, if none of the above are convenient, you can use our `toFile` helper:
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 文档。

解析 Webhook 负载

对于大多数用例，您可能希望同时验证 Webhook 并解析 payload (负载)。为了实现这一点，我们提供了方法 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, // env var used by default; explicit here.
});

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, // env var used by default; explicit here.
});

export async function webhook(request: Request) {
  const headersList = headers();
  const body = await request.text();

  try {
    client.webhooks.verifySignature(body, headersList);

    // Parse the body after verification
    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（API 错误）的子类：

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

错误代码如下：

状态码	错误类型
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

请求 ID

有关调试请求的更多信息，请参阅 这些文档

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 连接进行的 函数调用。

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 配合使用，请使用 AzureOpenAI 类而不是 OpenAI 类。

[!IMPORTANT] 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 选项来配置或禁用此功能：

// Configure the default for all requests:
const client = new OpenAI({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
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 选项配置此设置：

// Configure the default for all requests:
const client = new OpenAI({
  timeout: 20 * 1000, // 20 seconds (default is 10 minutes)
});

// Override per-request:
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

有关调试请求的更多信息，请参阅 这些文档

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 = [];
  // Automatically fetches more pages as needed.
  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);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

实时 API

实时 API 使您能够构建低延迟、多模态的对话体验。它目前支持文本和音频作为输入和输出，以及通过 WebSocket 连接进行 函数调用。

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 配合使用此库，请使用 AzureOpenAI 类而不是 OpenAI 类。

[!IMPORTANT] The Azure API shape slightly differs from the core API shape which means that the static types for responses / params won't always be correct.

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,
  apiVersion: '<The API version, e.g. 2024-10-01-preview>',
});

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

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

关于 Azure API 支持的更多信息，请参阅 azure.md。

高级用法

访问原始 Response (响应) 数据（例如：headers (头部)）

通过所有方法返回的 APIPromise 类型上的 .asResponse() 方法可以访问 fetch() 返回的“原始”Response (响应)。 该方法在接收到成功响应的头部后立即返回，并且不会消耗响应体，因此您可以自由编写自定义解析或流式处理逻辑。

您还可以使用 .withResponse() 方法获取原始 Response (响应) 以及解析后的数据。 与 .asResponse() 不同，此方法会消耗响应体，并在解析完成后返回。

const client = new OpenAI();

const httpResponse = await client.responses
  .create({ model: 'gpt-5.2', input: 'say this is a test.' })
  .asResponse();

// access the underlying web standard Response object
console.log(httpResponse.headers.get('X-My-Header'));
console.log(httpResponse.statusText);

const { data: modelResponse, response: raw } = await client.responses
  .create({ model: 'gpt-5.2', input: 'say this is a test.' })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(modelResponse);

日志记录

[!IMPORTANT] All log messages are intended for debugging only. The format and content of log messages may change between releases.

日志级别

日志级别可以通过两种方式配置：

1. 通过 OPENAI_LOG 环境变量
2. 使用 logLevel 客户端选项（如果设置则覆盖环境变量）

import OpenAI from 'openai';

const client = new OpenAI({
  logLevel: 'debug', // Show all log messages
});

可用的日志级别，从最详细到最少：

• 'debug' - 显示调试消息、信息、警告和错误
• 'info' - 显示信息消息、警告和错误
• 'warn' - 显示警告和错误（默认）
• 'error' - 仅显示错误
• 'off' - 禁用所有日志记录

在 'debug' 级别下，所有 HTTP 请求和响应都会被记录，包括头部和主体。 某些与身份验证相关的头部会被脱敏，但请求和响应主体中的敏感数据可能仍然可见。

自定义日志记录器

默认情况下，此库将日志记录到 globalThis.console。您也可以提供自定义日志记录器。 大多数日志库都受支持，包括 pino、winston、bunyan、consola、signale 和 @std/log。如果您的日志记录器无法工作，请提交一个 Issue。

当提供自定义日志记录器时，logLevel 选项仍控制哪些消息被发出，低于配置级别的消息将不会发送到您的日志记录器。

import OpenAI from 'openai';
import pino from 'pino';

const logger = pino();

const client = new OpenAI({
  logger: logger.child({ name: 'OpenAI' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});

发起自定义/未文档化的请求

此库已针对便捷访问文档化 API 进行了类型定义。如果您需要访问未文档化的端点、参数或响应属性，该库仍然可以使用。

未文档化的端点

要向未文档化的端点发起请求，您可以使用 client.get、client.post 和其他 HTTP 动词。 在发起这些请求时，客户端的选项（如重试）将被尊重。

await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});

未文档化的请求参数

要使用未文档化的参数发起请求，您可以在未文档化的参数上使用 // @ts-expect-error。 此库在运行时不验证请求是否与类型匹配，因此您发送的任何额外值都将原样发送。

client.chat.completions.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});

对于使用 GET 动词的请求，任何额外参数将在查询参数中，所有其他请求将在主体中发送额外参数。

如果您想显式发送额外参数，可以使用 query、body 和 headers 请求选项来实现。

未文档化的响应属性

要访问未文档化的响应属性，您可以在响应对象上使用 // @ts-expect-error 来访问响应对象，或将响应对象强制转换为所需类型。 与请求参数一样，我们不验证或从 API 响应中剥离额外属性。

自定义 fetch 客户端

如果你想使用不同的 fetch 函数，你可以选择全局 polyfill（填充）：

import fetch from 'my-fetch';

globalThis.fetch = fetch;

或者将其传递给客户端：

import OpenAI from 'openai';
import fetch from 'my-fetch';

const client = new OpenAI({ fetch });

Fetch 选项

如果你想在不过载 fetch 函数的情况下设置自定义 fetch 选项，可以在实例化客户端或发起请求时提供一个 fetchOptions 对象。（特定于请求的选项会覆盖客户端选项。）

import OpenAI from 'openai';

const client = new OpenAI({
  fetchOptions: {
    // `RequestInit` 选项
  },
});

配置代理

要修改代理行为，你可以提供自定义的 fetchOptions，为请求添加特定运行时的代理选项：

Node ^[文档]

import OpenAI from 'openai';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new OpenAI({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

Bun ^[文档]

import OpenAI from 'openai';

const client = new OpenAI({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

Deno ^[文档]

import OpenAI from 'npm:openai';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new OpenAI({
  fetchOptions: {
    client: httpClient,
  },
});

常见问题

语义化版本控制

本包通常遵循 SemVer（语义化版本控制） 规范，尽管某些向后不兼容的更改可能会作为次要版本发布：

1. 仅影响静态类型而不破坏运行时行为的更改。
2. 库内部更改，技术上虽然是公开的，但不打算或记录供外部使用。(如果您依赖此类内部功能，请提交 GitHub 问题告知我们。)
3. 我们预计在实践中不会影响绝大多数用户的更改。

我们非常重视向后兼容性，并努力确保您拥有顺畅的升级体验。

我们非常期待您的反馈；如有问题、错误或建议，请提交 问题。

要求

支持 TypeScript >= 4.9。

支持以下运行时环境：

• Node.js 20 LTS（长期支持版）或更高版本（非 EOL（生命周期结束） 版本）。

• Deno v1.28.0 或更高版本。

• Bun 1.0 或更高版本。

• Cloudflare Workers。

• Vercel Edge Runtime。

• Jest 28 或更高版本，配合 "node" 环境（目前不支持 "jsdom"）。

• Nitro v2.6 或更高版本。

• Web 浏览器：默认禁用以避免暴露你的秘密 API 凭证。通过显式设置 dangerouslyAllowBrowser 为 true 来启用浏览器支持。

  更多说明

  为什么这很危险？

  启用 dangerouslyAllowBrowser 选项可能是危险的，因为它会将你的秘密 API 凭证暴露在客户端代码中。Web 浏览器本质上比服务器环境安全性更低，任何能够访问浏览器的用户都可能检查、提取和滥用这些凭证。这可能导致未经授权的访问，使用你的凭证，并可能危及敏感数据或功能。

  何时这可能不危险？

  在某些启用浏览器支持可能不会构成重大风险的场景中：

  • 内部工具：如果应用程序仅在受控的内部环境中使用，且用户可信，则凭证泄露的风险可以降低。
  • 范围有限的公共 API：如果你的 API 范围非常有限，且暴露的凭证无法访问敏感数据或关键操作，则泄露的潜在影响会降低。
  • 开发或调试目的：临时启用此功能可能是可以接受的，前提是凭证是短期的，不在生产环境中使用，或经常轮换。

请注意，React Native 目前尚不受支持。

如果你对其它运行时环境感兴趣，请在 GitHub 上提交或点赞一个问题。

贡献

请参阅 贡献文档。

openai-node 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js 环境：已安装 Node.js 及 npm 包管理器。
• API 密钥：拥有一个有效的 OpenAI API Key（建议通过环境变量 OPENAI_API_KEY 存储）。

安装步骤

使用 npm 或 yarn 安装官方 SDK：

npm install openai

如果您使用 Deno 或 JSR，也可以使用以下方式：

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

基本使用

初始化客户端并调用 API 生成文本。以下是使用标准的 Chat Completions API 的示例：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

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

运行上述代码前，请确保已在终端中设置环境变量：

export OPENAI_API_KEY="your-api-key-here"