本指南涵蓋的內容
本指南說明如何建立或登入 OpenAI 平台帳戶、新增付款方式、建立 Secret Key、發出第一次請求、查看用量,以及排除常見的 Key 錯誤。適合想在自己的腳本或應用程式中呼叫 OpenAI API 的人。本指南不涵蓋 ChatGPT 訂閱,那是另外計費的產品。
前置條件
- 帳戶: 一個你能掌控並能找回的 OpenAI 登入方式。
- 付款: OpenAI 在你所在地區提供的付款方式或預付選項。可用方式因地區而異,我無法核實完整清單(UNKNOWN)。
- 基本的程式能力: 你應能開啟終端機、設定環境變數並執行簡短腳本。範例使用
curl,以及配合 Node.js 的 JavaScript。
步驟 1:建立或登入 OpenAI 平台帳戶
開啟 API keys 頁面。依提示登入,或建立帳戶。請使用你本人擁有的帳戶。
如果你所在的組織已有 API 帳戶,請由組織擁有者邀請你,而不是共用 Key。OpenAI 的成員管理指南對此有說明。
步驟 2:新增付款方式並了解依用量計費
開啟帳單設定頁面,此連結見於 OpenAI 的錯誤參考。依頁面提示新增付款方式或額度。
API 依用量計費。OpenAI API 定價頁面與開發者定價參考列出了費率。參考文件說明,除非另有標註,價格以每 100 萬 token 計,並另列部分內建工具。開始前請查看你計畫使用的模型費率。本指南不列出具體價格,因為價格會變動,且因模型而異。
如果預付餘額用完,請求可能因 credit_balance_exhausted 錯誤而失敗。請參閱下方的排除故障段落。
步驟 3:建立 Secret Key 並只複製一次
- 開啟 API keys 頁面。
- 建立新的 Secret Key,並命名為將使用它的應用程式或腳本。
- 立即複製該 Key,並存入密碼管理工具。OpenAI 的 API Key 說明文章 指出,完整的 Secret Key 只會在建立時顯示。若遺失,請建立新 Key 並更新你的應用程式。已刪除的 Key 無法再使用。
- 切勿將 Key 貼到聊天、截圖或原始碼中。
我無法讀取 API keys 頁面的文字內容,因此按鈕名稱可能與此處的步驟不同。
步驟 4:發出第一次 API 呼叫
將 Key 存入環境變數,讓程式碼中永遠不包含它。在 macOS 或 Linux 上,於終端機執行以下指令,並將佔位符替換為你的 Key:
export OPENAI_API_KEY="your_api_key_here"
在 Windows PowerShell 中使用以下指令,然後開啟新的終端機視窗:
setx OPENAI_API_KEY "your_api_key_here"
用 curl 測試。將 MODEL_ID 替換為你的帳戶可用的模型:
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "MODEL_ID",
"input": "Say hello in one short sentence."
}'
若使用 JavaScript,請先執行 npm install openai 安裝官方 SDK,然後將以下內容存為 hello.mjs:
import OpenAI from "openai";
// The SDK reads OPENAI_API_KEY from the environment.
const client = new OpenAI();
const response = await client.responses.create({
model: "MODEL_ID",
input: "Say hello in one short sentence.",
});
console.log(response.output_text);
執行 node hello.mjs。開發者快速入門使用的正是這種模式。如果出現錯誤,請前往排除故障段落。
步驟 5:查看用量
成功呼叫後,開啟平台帳戶中的用量面板,確認該請求已出現。OpenAI 的用量匯出文章介紹了 API Usage Dashboard。在那裡你可以查看每月用量,並以 CSV 匯出整個日曆月或月至今的用量或費用資料。如果請求尚未出現,請稍後再查看。我無法核實需要多久(UNKNOWN)。
可以免費使用 API 嗎?
OpenAI 的定價頁面描述的是依用量計費的費率。我無法從官方頁面核實新帳戶是否獲得免費額度,或任何模型是否有免費方案(UNKNOWN)。定價參考中有部分項目標示為免費或包含免費額度,例如部分檔案儲存的 1 GB 免費額度,以及一個免費的內容審核模型。在假設任何呼叫免費之前,請查看目前定價頁面中你所用模型與工具的說明。
如何保護 Key 的安全?
請遵循 OpenAI 的 API Key 安全最佳實務。實際做法如下:
- 切勿將 Key 提交到 git。 將 Key 存放在環境變數或本機密鑰儲存區中,並把
.env檔案加入.gitignore。每次推送前都檢查暫存的變更。 - 外洩時立即輪替。 如果 Key 出現在儲存庫、日誌、截圖或聊天中,請在 API keys 頁面刪除它、建立新 Key,並更新你的應用程式。已刪除的 Key 會停止運作。
- 每個專案使用一把 Key。 為每個應用程式、腳本和團隊成員配發各自的 Key。OpenAI 表示分享 API Key 違反其使用條款,因此請邀請隊友使用各自的帳戶。
- 設定到期日。 專案 Key 可以設定到期日期。請在舊 Key 到期前建立替代 Key,並在新 Key 運作正常後撤銷舊 Key。
- 不要把 Key 交給支援人員。 任何支援管道都不需要你的 Key。
為什麼我的 Key 無法使用?
請閱讀狀態碼與錯誤訊息,然後對照 OpenAI 的錯誤參考進行比對。
| 狀態碼與訊息 | 可能原因 | 處理方式 |
|---|---|---|
401 Incorrect API key provided | Key 錯誤、已刪除,或來自其他帳戶 | 在 API keys 頁面檢查 Key。確保程式碼中始終使用同一把 Key。參見 Incorrect API key provided。 |
401 You must be a member of an organization | 你的帳戶不在擁有該 Key 的組織中 | 請組織管理員邀請你。 |
401 IP not authorized | 請求來自允許清單之外的 IP 位址 | 從允許的 IP 發送請求,或更新允許清單。 |
429 Rate limit reached for requests | 短時間內請求或 token 過多 | 放慢請求速度;若有 Retry-After 標頭,請依其提示。參見速率限制指南與 429 排除故障文章。 |
429 credit_balance_exhausted | 預付額度已用完 | 在帳單設定中新增額度。只重試無法解決。 |
429 且錯誤類型為 insufficient_quota | 觸發了與帳單相關的限制 | 檢查帳單與任何用量限制,然後參閱 429 排除故障文章。 |
403 Country, region, or territory not supported | 從不受支援的國家或地區存取 API | 查看錯誤參考所連結的受支援國家與地區清單。 |
若遇到此處未列出的訊息,請在錯誤參考中搜尋完全相同的文字。我無法核實每一條 403 訊息的完整含義(UNKNOWN)。
Cue 需要我自己的 OpenAI API Key 嗎?
UNKNOWN。我查看了 Cue 的公開頁面:heycue.io、定價與常見問題。頁面列出了模型,但我讀過的內容都沒有說明 Cue 自身功能是否需要你的 OpenAI API Key。在依賴任一方式之前,請檢查你的 Cue 設定與方案說明。切勿把 API Key 交給 Cue 支援。
未驗證或無法取得的項目
platform.openai.com/docs/quickstart發生跨網域重新導向,未被追蹤。我改用developers.openai.com/api/docs/quickstart的 Markdown 版本。platform.openai.com/api-keys未回傳可讀的頁面文字。Key 步驟依據 OpenAI 的說明文章,按鈕名稱未經核實。openai.com/api/pricing/在我的抓取中被截斷。費率來自開發者定價參考。本文未列出任何價格。- 新帳戶的免費額度或免費方案:UNKNOWN。
- 每一條 403 訊息的含義:除國家或地區這種情況外,均為 UNKNOWN。
- Cue 是否需要你自己的 OpenAI API Key:UNKNOWN。
Cue 是由 Sophon LLC 開發的獨立桌面 AI 助理。 使用 Cue 處理你獲授權的文件、筆記與任務,可選擇 Claude 與 GPT 模型。請查看 Cue 方案說明,了解你的帳戶包含哪些內容與可用模型。你的 OpenAI 帳戶的 API Key、帳單與用量仍由 OpenAI 管理。