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)。 ## 安装 sh npm install openai ### 从 JSR 安装 sh 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) 导入，无需安装步骤： ts 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)。您可以使用以下代码从模型生成文本。 ts 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); 之前的标准（长期支持）用于生成文本的是 Chat Completions API (https://platform.openai.com/docs/api-reference/chat)。您可以使用以下代码通过该 API 从模型生成文本。 ts 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); ## 工作负载身份认证 对于安全的自动化环境（如云管理的 Kubernetes、Azure 和 GCP），您可以使用工作负载身份认证，使用来自云身份提供商的短期令牌，而不是长期 API 密钥。workloadIdentity 参数与 apiKey 互斥。 ### Kubernetes（服务账户令牌） ts 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（托管标识） ts 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（计算引擎元数据） ts 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(), }, }); ### 自定义主题令牌提供者 ts 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 分钟））： ts 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) 进行流式响应。 ts 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 辅助函数的返回值 ts 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 FileAPI，可以传递一个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 解析为事件对象。 ts 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 字符串（不要先解析它）。验证签名后，您需要自行解析 body。 ts 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('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 的子类： ts 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 | | 不适用 | APIConnectionError | ## 请求 ID > 有关调试请求的更多信息，请参阅这些文档 (https://platform.openai.com/docs/api-reference/debugging-requests) SDK 中的所有对象响应都提供一个 _request_id 属性，该属性来自 x-request-id 响应头，以便您可以快速记录失败的请求并将其报告给 OpenAI。 ts 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： ts 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)。 ts 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 类。 > [!IMPORTANT] > Azure API 的形状与核心 API 形状略有不同，这意味着响应/参数的静态类型并不总是正确的。 ts 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 选项来配置或禁用此功能： js // 为所有请求配置默认值： 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 选项进行配置： ts // 为所有请求配置默认值： 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。 ts const response = await client.responses.create({ model: 'gpt-5.2', input: 'testing 123' }); console.log(response._request_id); // req_123 您也可以使用 .withResponse() 方法访问请求 ID： ts 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 语法跨页面迭代项目： ts async function fetchAllFineTuningJobs(params) { const allFineTuningJobs = []; // 根据需要自动获取更多页面。 for await (const fineTuningJob of client.fineTuning.jobs.list({ limit: 20 })) { allFineTuningJobs.push(fineTuningJob); } return allFineTuningJobs; } 或者，您可以一次请求单个页面： ts 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)。 ts 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 类。 > [!IMPORTANT] > Azure API 的形状与核心 API 形状略有不同，这意味着响应/参数的静态类型并不总是正确的。 `ts 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);