OpenAI 的文件非常完整。但也分散在六份不同的 API 參考文件、三份移轉指南，以及一份每月更新的變更記錄裡。
2024 年的教學引用的都是已經被淘汰的模型、被刪除的參數。你搜尋「OpenAI streaming example」，找到四種不同寫法——其中只有兩種還能用。
這份教學涵蓋 2026 年 7 月為止 OpenAI API 的所有主要功能，按照你應該學習的順序排列，而且附上可以跑的程式碼。
沒有被淘汰的參數。沒有「請查最新文件」的推託之詞。每個範例都經過目前 API 的實際測試。
2026 年的 OpenAI API 版圖
OpenAI 目前維護三套主要的 API，知道該用哪一套，可以避免很多混亂。
Chat Completions API（/v1/chat/completions）：經典款。無狀態（stateless）、一問一答。送訊息出去，拿完成內容（completion）回來。支援 streaming、function calling、JSON mode 和 structured outputs。90% 的應用程式都在用它。如果你不確定要用哪一套，就用這個。
Responses API（/v1/responses）：比較新，有狀態（stateful）。由伺服器端維護對話狀態，你不用自己管理訊息陣列。內建工具支援 web search、file search 和 computer use。更適合複雜的 agent 工作流程——模型需要在多個回合中協調多個工具。代價是：對訊息歷史的控制比較少，而且 API 仍在演進中。
Agents SDK：最新加入的。一套用來打造持久性 AI agent 的框架，內建護欄（guardrails）、專門 agent 之間的交接（handoff）、以及 tracing。比起原始 API 更受限——你用彈性換取常見 agent 模式更快的開發速度。這裡不詳細介紹；Building AI Agents 指南有完整說明。
目前的模型陣容（2026 年 7 月）：
| 模型 | Input $/M | Output $/M | Context | 最適合 |
|---|---|---|---|---|
| GPT-5.5 | $5.00 | $30.00 | 1M | 最高效能，複雜推理 |
| GPT-5.4 | $2.50 | $15.00 | 1M | 效能強勁，性價比更高 |
| GPT-5.4 Mini | $0.75 | $4.50 | 400K | 日常任務，成本與品質兼顧 |
| GPT-5.4 Nano | $0.20 | $1.25 | 128K | 大量簡單任務 |
| o4-mini | $1.10 | $4.40 | 200K | 數學、邏輯、程式題（推理特化） |
身分驗證。 把 API Key 設定成 OPENAI_API_KEY 環境變數——絕對不要寫死在程式裡。正式環境的 Key 管理、輪換、權限範圍與虛擬 Key 架構，請見我們的 API Key 管理指南。
Chat Completions API：地基
每一項 OpenAI 整合都是從這裡開始的。
基本聊天呼叫——Python：
from openai import OpenAI
client = OpenAI(
base_url="https://api.tokspan.com/v1",
api_key="ts-your-key-here"
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "You are a software engineer. Answer with code when appropriate."},
{"role": "user", "content": "Write a Python function to check if a string is a palindrome."}
],
temperature=0.3, # Low = deterministic, good for code
max_tokens=500, # Cap output length
top_p=0.95 # Nucleus sampling —usually leave at default
)
print(response.choices[0].message.content)每個關鍵參數：
model——要用哪台模型。正式環境請用日期版本 ID（gpt-5.5-2025-06-15），不要用別名（gpt-5.5）。別名會默默升級到新的 snapshot，可能改變你的提示詞行為。messages——由帶有role（「system」、「user」、「assistant」）與content的訊息物件組成的陣列。系統訊息設定行為。使用者訊息就是請求。assistant 訊息是先前模型的回應——要保留對話上下文就得一起帶上。temperature——0 到 2。寫程式與事實型任務用 0～0.3。聊天與創作用 0.7～1.0。腦力激盪用 1.0 以上。max_tokens——輸出長度的硬性上限。模型撞到這個上限就會停下來，就算是句子講到一半。大部分任務都設得寬鬆一點（500～4,000）。top_p——temperature 的替代方案。通常保持預設值（1.0），只用 temperature 控制隨機性就好。
寫對系統訊息。 好的系統訊息要具體，不要講大道理。爛範例：「你是個好用的 AI 助理。」好範例：「你是 Python 程式碼審查員。針對每一段程式碼，找出：(1) 潛在 bug、(2) 效能問題、(3) 風格違規。用條列式格式回應。每個條目不超過 30 字。」
多回合對話。 API 是無狀態的。它不記得你先前呼叫過什麼。
要對話，就得每次把整段訊息歷史都送過去——系統訊息＋先前所有使用者與 assistant 訊息＋新的使用者訊息。當歷史接近模型的上下文上限時，就刪掉最舊的訊息，或把對話做摘要。截斷比出錯好；摘要又比截斷好。
Streaming：即時回應
非串流模式：使用者要等 3～8 秒，然後一次看到完整回應。串流模式：使用者從約 0.4 秒開始，即時看到文字出現。UI 上的差別，就是「覺得好慢」跟「覺得秒回」的差別。
Python 的串流實作：
stream = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Explain recursion."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)Node.js 的串流實作：
const stream = await client.chat.completions.create({
model: "gpt-5.5",
messages: [{ role: "user", content: "Explain recursion." }],
stream: true
});
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}需要處理的邊緣情況： 空白 chunk（串流開頭的前幾個 chunk 常常沒有內容——API 還在處理中）。連線中斷（把串流包進 try/except，中途失敗就用同一組訊息重試）。追蹤 finish_reason（最後一個 chunk 會包含 finish_reason——檢查它，才能知道模型是自然結束，還是撞到了上限）。
Function Calling：給你的 LLM 工具
模型不會執行程式。它會產生一段 JSON，描述該呼叫哪個函式、帶哪些參數。執行函式的是你的程式碼。
你把結果送回給模型。模型用這個結果產生最終回應。這就是所有 AI agent 背後共同的架構。
完整的天氣 agent 範例：
import json
# Step 1: Define the tool
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city. Returns temperature in Celsius and conditions.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. 'Tokyo'"}
},
"required": ["city"]
}
}
}]
# Step 2: User asks a question that needs the tool
response = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
tools=tools,
tool_choice="auto" # Model decides whether to use a tool
)
# Step 3: Check if model wants to call a tool
msg = response.choices[0].message
if msg.tool_calls:
tool_call = msg.tool_calls[0]
args = json.loads(tool_call.function.arguments)
# Step 4: Execute the function (in reality, call a weather API)
weather_result = get_actual_weather(args["city"])
# Step 5: Send the result back
messages = [
{"role": "user", "content": "What's the weather in Tokyo?"},
msg, # The assistant's tool_call message
{"role": "tool", "tool_call_id": tool_call.id, "content": str(weather_result)}
]
final_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages
)
print(final_response.choices[0].message.content)平行 function calling。 定義多個工具。如果這些工具彼此獨立，模型可能一次要求好幾個——「取得東京 AND 大阪的天氣」。你的程式碼要能處理回應裡的多個 tool_calls，平行執行它們（asyncio.gather），再把所有結果一起送回去。
Function calling 最佳做法。 工具描述就是提示詞——寫得清楚一點，並附上每個工具該在什麼時候用的範例。參數要嚴格限制——用 enum，不要用自由文字字串。OpenAI 的 function calling 指南 詳細涵蓋了串流 tool calls、平行執行等邊緣情況。
讓工具保持冪等（idempotent）。工具執行失敗時，把錯誤訊息送回給模型——它常常可以靠嘗試不同參數來恢復。
跨供應商的 function calling 比較——OpenAI、Anthropic、Google、DeepSeek——包括哪些功能在轉成 OpenAI 相容格式後還能存活，完整的比較請見 tool calling 比較。
Structured Outputs：保證是 JSON
JSON mode（response_format={"type": "json_object"}）是「暗示」你要 JSON。模型通常會照做。Structured Outputs（response_format={"type": "json_schema", ...}）則是「保證」——模型的 token 取樣會被限制成只會產生符合你 schema 的有效 JSON。
什麼時候用哪一種。 JSON mode：快速 prototyping、內部工具、偶爾遇到壞掉的 JSON 也沒關係的情況。Structured Outputs：正式環境 API、面向客戶的功能、任何無效 JSON 會引發連鎖失敗的情況。OpenAI 的 Structured Outputs 文件 涵蓋完整的 schema 定義語法與支援的模型。
定義 schema——履歷解析器範例：
response = client.chat.completions.create(
model="gpt-5.4", # Structured Outputs supported on GPT-5.4+
messages=[{"role": "user", "content": f"Extract information from this resume:\n\n{resume_text}"}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "resume_extraction",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"skills": {"type": "array", "items": {"type": "string"}},
"years_experience": {"type": "integer"},
"current_role": {"type": "string"}
},
"required": ["name", "skills", "years_experience"]
}
}
}
)
resume_data = json.loads(response.choices[0].message.content)
# Guaranteed to match your schema. No try/except json.loads needed.正式環境部署檢查清單
環境管理。 API Key 放進機密保管庫（AWS Secrets Manager、HashiCorp Vault、Doppler），不要放在 .env 檔裡。每 90 天輪換一次 Key。開發、測試、正式環境三種環境用不同的 Key，並配上不同的預算上限與模型許可清單。
正式環境的錯誤處理。 每一次 API 呼叫都要包上「指數退避＋抖動」的重試。對持續失敗的供應商設定斷路器（circuit breaker）——暫停對它路由 30 秒、探測、恢復健康就重新啟用。永遠不要把原始的 API 錯誤直接丟給使用者——轉成友善的訊息，細節留在內部記錄。
成本監控。 分別追蹤每個使用者、每項功能、每台模型的成本。在正常每日支出的 2 倍設定異常警示。
那張 $500 的驚人帳單，通常發生在沒人盯著的時刻。每日成本摘要 10 秒就能掃完。
速率限制管理。 搞清楚自己等級的 RPM 與 TPM 上限。每個回應都要讀 x-ratelimit-remaining-* 標頭。剩下 30% 就放慢。剩下 10% 就停下來。
從反應式退避到預測性節流，完整的速率限制架構請見我們的正式環境速率限制處理指南。
另一條路。 聚合平台在基礎設施層級替你處理身分驗證、錯誤復原、成本記錄與速率限制管理。你只要專心寫應用程式邏輯。
代價是對請求路徑的控制變少。對大部分團隊來說，省下來的時間勝過放棄的控制權。
常見問題
GPT-5.5 跟 o4-mini 差在哪？
GPT-5.5 是通用模型，適合聊天、寫程式、分析與生成。o4-mini 是推理特化模型——回應前思考更久，因此在數學、邏輯題與形式推理上更強，但更慢，每個 token 也更貴。
日常任務用 GPT-5.5。平常會拿出計算機或寫形式證明的任務，用 o4-mini。
我需要改用 Responses API 取代 Chat Completions 嗎？
還不需要。Chat Completions 穩定、支援最廣，能處理 90% 的使用情境。Responses API 多了狀態管理與內建工具（web search、file search），但比較新，還在演進。
先從 Chat Completions 開始。當你需要它的特定功能時，再移轉到 Responses API。
怎麼降低 OpenAI API 的成本？
簡單任務用 GPT-5.4 Mini（$0.75/$4.50）代替 GPT-5.5（$5/$30）。啟用 prompt caching——被快取的輸入打 5 折。不急的工作用 batch API——24 小時內回覆打 5 折。
或者用聚合平台——用量合併計價加上自動模型路由，不用手動切換模型就能降低成本。砍帳單技巧指南 逐一講解每種策略。
可以把 OpenAI SDK 用在非 OpenAI 的模型上嗎？
可以。大部分供應商都提供 OpenAI 相容的 endpoint。
改 base_url 和 api_key 就行。你的程式碼完全不動。這就是 OpenAI 相容標準最大的優勢——你不會被綁死在任何一家供應商。
OpenAI 把我正在用的模型淘汰了怎麼辦？
OpenAI 通常會提前 1～3 個月通知。固定用日期版本 ID（gpt-5.5-2025-06-15），不要用別名（gpt-5.5），才能控制自己何時移轉。
在淘汰日期前，用你的提示詞測過替代模型。設定一台非 OpenAI 的備援模型，這樣你就不必配合 OpenAI 的時間表被迫移轉。
OpenAI API 會成為業界標準不是沒有理由：成熟的 SDK、完整的文件、優先支援它的生態系。但 2026 年是這套標準開始出現裂痕的第一年——Anthropic 的原生協定、Google 的自動 function calling、DeepSeek 的價格壓力，各自把開發者往那些「轉成 /v1/chat/completions 之後就活不下來」的功能拉去。值得追蹤的問題：OpenAI 的 Agents SDK 會成為重新統一生態系的下一代業界標準，還是會透過推出只能在 OpenAI 自家基礎設施上用的功能，加速生態系的分裂？
開始寫程式——用你自己的方式駕馭 OpenAI 的 API。準備好之後，再用同一支 SDK 加上 Claude、Gemini 和 DeepSeek——因為 2026 年唯一安全的賭注，就是能在每一家供應商上跑的程式碼。