Skip to content
AI Blog

OpenAI ChatGPT API 開發指南

最後更新：2026-08-12· 18 分鐘閱讀

🚀 快速通道

  • ChatGPT 國內版：點擊直達↗
  • 穩定鏡像站：開啟鏡像↗
  • 官方 ChatGPT：chatgpt.com ↗

OpenAI ChatGPT API 開發指南

更新時間：2026-08-12

導讀

調通一次 curl 只是起點。生產接入需要：金鑰隔離、可觀測性、限流與重試、以及對 Responses API / Chat Completions 雙軌並存的遷移預案——Assistants API 還可能處於 legacy 階段。本文面向後端與全端，假設你已讀過 API 快速入門。欄位與端點以 API Reference 為準。

推薦架構：BFF / Gateway

[Web / App] ──→ [你的 BFF / Gateway] ──→ api.openai.com
                      │
            租戶鑑權、QPS 限流、
            Prompt 模板、RAG 注入、
            日誌與 token 計量
層級應做禁止
用戶端UI、工作階段 id持有 OpenAI Key
BFF組裝 messages、合併檢索結果把 Key 下發瀏覽器
Worker非同步批次處理、長任務無 timeout 裸 HTTP
OpenAI推理業務 RBAC

鑑權與 Key 生命週期

Authorization: Bearer sk-...
Content-Type: application/json
  • Key 從環境變數或 Vault 讀取；啟動時校驗存在性。
  • 多租戶 SaaS：不要讓租戶共享可被提取的 Key；由後端統一代理。
  • 輪替流程：新 Key 上線 → 雙寫驗證 → 切流量 → 撤銷舊 Key。

Platform 操作細節：Platform 概覽。

選擇 API 形態

形態端點（範例）適用
Responses API/v1/responses官方 Quickstart 常指向；工具呼叫
Chat Completions/v1/chat/completions存量、第三方範例多
Assistants API/v1/assistants 等有狀態 Thread；查文件是否 legacy
Embeddings/v1/embeddings向量，見 embeddings 指南

新專案： 開啟 Quickstart 跟隨當前推薦。舊專案： 設遷移里程碑，避免無限期雙棧。Assistants 遷移見 Assistants 開發指南。

請求設計：messages 與角色

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "你是訂單客服。僅回答物流與退換貨；其他轉人工。"},
    {"role": "user", "content": "訂單 12345 到哪了？"}
  ],
  "temperature": 0.2,
  "max_tokens": 512
}

gpt-4o-mini 僅為範例 model ID，請替換為文件當前型號。若跟進旗艦換檔，見 GPT-6 Astra（gpt-6-astra）：生產路由務必保留回退到既有正式檔，並記錄核對日期。

角色用途
system規則、工具說明、輸出格式
user終端使用者或上游系統
assistant歷史回覆，多輪上下文
tool / function工具回傳（視 API 版本）

多輪由你的服務維護 messages；接近上下文上限時摘要舊輪次。參數調優：文字生成。

串流輸出（SSE）

聊天 UI 建議 stream: true 降低首字延遲：

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [{"role": "user", "content": "用五言絕句描述清晨寫程式"}]
  }'

生產要點：

  • 用戶端斷開時取消上游請求，避免白燒 token。
  • 串流同樣計費；拼接完整結果後再落庫。
  • 閘道正確處理 text/event-stream 與中間代理緩衝。

工具呼叫（Tools / Functions）

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "查一下上海今天天氣"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "使用者詢問某城市當前天氣時呼叫",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
實踐說明
schema 穩定便於 prompt 回歸
伺服器端校驗參數勿執行模型生成的 SQL/URL
逾時與冪等外部 API 失敗給降級文案

複雜編排：Agents SDK、Responses API。

錯誤處理與重試

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()
RETRY = {429, 500, 502, 503, 504}

def chat_with_backoff(**kwargs):
    for i in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** i)
        except APIStatusError as e:
            if e.status_code not in RETRY:
                raise
            time.sleep(2 ** i)
    raise RuntimeError("max retries")
  • 401 / 400：設定或請求體錯誤，勿盲目重試。
  • 429：尊重 Retry-After（若有）。
  • 日誌保留 x-request-id。

限流、成本與快取

  • 閘道做租戶級 QPS，避免單客戶打滿組織 RPM。
  • 長上下文單獨限流；輸入 token 常是成本大頭。
  • 相同 FAQ + 相同 system 可考慮短 TTL 快取（注意隱私與刷新）。
  • 按 model、route、tenant 聚合 token 與錯誤率。

結構化輸出

  1. system 宣告 JSON schema 與「只輸出 JSON」。
  2. 使用官方 Structured Outputs / JSON mode（若 model 支援）。
  3. 伺服器端 JSON Schema 校驗；失敗則重試或降級。

Prompt 模板：Prompt Engineering。

生產上線清單

安全

  • Key 不進前端與行動端
  • 輸入/輸出日誌去識別
  • 高風險場景人工覆核

可靠性

  • timeout（連線 + 讀）
  • 429/5xx 退避
  • 連續失敗時熔斷降級

品質

  • golden prompts 發布前回歸
  • system prompt 版本化（Git / CMS）

合規

  • 使用者同意與資料留存政策
  • 按業務做內容安全過濾

與 Assistants API 的關係

Assistants 提供 Assistant / Thread / Run 有狀態抽象，內建 File Search 等。官方可能引導至 Responses API 或 Agents SDK。新功能立項前閱讀 Assistants 開發指南 的遷移說明，勿預設 Assistants 為長期主路徑。

常見問題

多微服務共用一個 Key 可以嗎？

可以但不推薦；至少按環境分 Key，最好按服務分，便於外洩隔離與配額分析。

如何實作多輪「記憶」？

自管 messages 或工作階段摘要；或用有狀態 API（Assistants 等），並評估 vendor lock-in 與成本。

stream 與非 stream 品質一樣嗎？

同參數下模型相同；差異在體驗與實作，非品質。

產品裡讓使用者自帶 Key（BYOK）？

可行但需嚴格隔離與稽核；多數產品由後端統一代理。

如何對比 OpenAI 與 Claude 成本？

相同評測集分別記錄 token 與延遲，查 OpenAI 定價 與 Anthropic 定價。

官方資源

下一步閱讀

行動路徑

今天：為現有呼叫加 timeout 與 429 退避。明天：接入 stream 並測首 token 延遲。本週：建立 20 條 golden prompts 回歸集，寫一頁 gateway 架構說明供團隊評審。

相關內容