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