OpenAI API Node.js / TypeScript 快速上手：npm install openai、example.mjs 第一个请求，到流式、函数调用、联网搜索

本文根据 OpenAI 官方《Developer quickstart》《SDKs and CLI》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 OpenAI 官方网站。API 是按用量计费的独立服务，与 ChatGPT 订阅分开计算，Key 的获取见 /guides/openai-api-key。

适用于谁

• 主要写 JavaScript 或 TypeScript、想在 Node.js 里调用 OpenAI API 的开发者；
• 看过 Python 版入门（见 /guides/openai-api-python-quickstart），想要同样的 Node 版的人；
• 想知道接下来各项能力在 Node 里怎么写、去哪里看的人。

结论先说

1. 官方有 TypeScript 和 JavaScript 的 SDK，适用于 Node.js、Deno、Bun 等服务端 JavaScript 环境，安装命令是 npm install openai。
2. 密钥放环境变量 OPENAI_API_KEY，SDK 会自动读取，代码里不用写密钥。
3. 第一个请求只有几行：import OpenAI from "openai"，new OpenAI()，client.responses.create({ model, input })，结果在 response.output_text。
4. 官方示例文件叫 example.mjs，用 node example.mjs 运行。
5. 这个 SDK 是给服务端用的，不要把密钥放进网页或手机 App 里。

图：本站根据 OpenAI 官方《Developer quickstart》 整理的示意图

一、创建并导出 API Key

先在官方控制台创建 API Key，怎么创建、怎么保管见 /guides/openai-api-key。官方建议把 Key 存在安全的地方，然后在终端里导出成环境变量：

• macOS 或 Linux：

export OPENAI_API_KEY="your_api_key_here"

• Windows（官方写法）：

setx OPENAI_API_KEY "your_api_key_here"

官方说明，所有 OpenAI SDK 都会自动读取系统环境里的密钥。需要提醒的是，setx 设置的变量对已经打开的终端窗口不生效，需要新开一个终端再运行；这是 Windows 命令行的一般行为，官方这一页没有写，请你自己确认一下。

二、安装 SDK，发出第一个请求

新建一个项目目录，在里面运行：

npm install openai

然后新建文件 example.mjs，写入官方示例：

javascript
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra", // 以官方模型页当天为准
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

运行：

node example.mjs

几秒后就能看到模型的输出。用 Deno 或 Bun 时，官方说用对应的命令。

为什么是 .mjs？.mjs 文件会被 Node 当作 ES 模块，所以可以直接用 import 和顶层的 await。如果你想用 .js 后缀，需要在 package.json 里设置模块类型，这是 Node 的通用用法，本文不展开。

请求的结构含义：

• model：用哪个模型；
• input：输入，可以是一个字符串，也可以是消息数组；
• response.output_text：把输出里的文字拼好的快捷属性。

这个 responses.create 就是 Responses API 的入口，它和旧的 Chat Completions 有什么区别，见 /guides/openai-responses-api。

三、接下来的能力，Node 里怎么写

官方快速入门页给了一系列 JavaScript 示例，下面按用途列出，并链到本站对应的详细教程：

1）带图片。 在 input 的 content 数组里加 { type: "input_image", image_url: "...", detail: "auto" }。传网址、Base64、文件 ID 的区别见 /guides/openai-api-image-input。

2）带文件（PDF）。 官方示例有三种：input_file 配 file_url；或先 client.files.create({ file: fs.createReadStream("..."), purpose: "user_data" }) 上传，再用 file_id 引用。

3）流式输出。 请求里加 stream: true，然后用 for await (const event of stream) 遍历事件。详细的事件类型和拼接方法见 /guides/openai-api-streaming。

4）函数调用。 在 tools 里放一个 type: "function" 的定义，模型会在 response.output 里返回调用请求。完整的五步流程见 /guides/openai-api-function-calling。

5）联网搜索。 官方快速入门页的写法是：

javascript
const response = await client.responses.create({
  model: "gpt-6-astra", // 以官方模型页当天为准
  tools: [{ type: "web_search" }],
  input: "今天有什么好消息？",
});

console.log(response.output_text);

联网搜索工具的计费和限制，以官方工具文档和价格页为准。

6）结构化 JSON。 用 Zod 定义结构再 responses.parse，见 /guides/openai-api-structured-outputs。

7）智能体。 官方有 @openai/agents 包，示例里用 Agent 和 run 搭了一个按语言分流的智能体；入门可看本站的 Agents SDK 教程 /guides/openai-agents-sdk-python-quickstart（Python 版），JS 版以官方文档为准。

四、出错时怎么处理

图：本站根据 OpenAI 官方《Developer quickstart》 整理的示意图，前两行的处理办法为本站补充

官方错误码页给出的 Node 捕获写法（类名与官方一致）：

javascript
import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra", // 以官方模型页当天为准
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("连不上 OpenAI API：", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("请求超过限额：", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("API 返回错误：", error.status, error.message);
  } else {
    throw error;
  }
}

各状态码的含义和处理见 /guides/openai-api-error-codes，限速问题见 /guides/openai-api-429-error。

五、费用和用量

调用 API 按用量计费，和 ChatGPT 订阅是分开的。想在发请求前先估算输入多少 token，见 /guides/openai-api-token-count-estimate。价格以官方价格页当天为准，见 /guides/openai-api-price-official-table；账单怎么看见 /guides/openai-api-pricing-billing。

五、读懂响应对象

response.output_text 只是方便的快捷属性。完整的响应里有个 output 数组，里面是一项项输出。官方的 Batch 页给出过一个例子：文字回答是一个 type 为 message 的项，它的 content 里有 type 为 output_text 的内容；模型要调用函数时，则是 type 为 function_call 的项，官方快速入门里的函数调用示例就是直接 console.log(response.output[0]) 看这一项。联网搜索、图像生成等工具也会在 output 里留下自己类型的项。所以当 output_text 是空的，不一定是出错了，可以先打印 response.output 看看里面是什么类型。

六、几个小建议

• 把示例里的字符串换成自己的内容之前，先原样跑通一次官方示例，确认密钥、网络和模型名都没问题；
• 密钥永远只放在服务器的环境变量或密钥管理里，不要提交到 Git 仓库；
• 不确定某个参数怎么写时，查官方 API 参考比搜索旧教程可靠，SDK 的细节以 openai-node 的 GitHub 说明为准（以上三条是本站建议，不是官方原文）。

常见问题

Q：必须用 TypeScript 吗？

不必须。官方 SDK 的名字是“OpenAI SDK for TypeScript and JavaScript”，两种都能用，快速入门示例用的是 JavaScript。

Q：可以在浏览器里直接用吗？

官方快速入门说的是“服务端 JavaScript 环境，如 Node.js、Deno 或 Bun”。浏览器里直接用密钥会泄露，做浏览器应用的典型做法是让自己的服务器去调用，需要实时语音的场景见 /guides/openai-api-realtime。

Q：还有别的语言吗？

官方页面列出 Python、.NET、Java、Go、Ruby 的 SDK，另有命令行工具 OpenAI CLI，可以到官方 SDKs and CLI 页面查看。

参考资料

• OpenAI 官方：Developer quickstart — https://developers.openai.com/api/docs/quickstart
• OpenAI 官方：SDKs and CLI — https://developers.openai.com/api/docs/libraries
• OpenAI 官方：Error codes — https://developers.openai.com/api/docs/guides/error-codes