OpenAI API 串接教學｜2026 年 Python SDK 從零開始完整指南

3 行 Python 就能呼叫 GPT

很多人以為串接 AI API 很複雜。

不是。

OpenAI 的 Python SDK 設計得非常簡潔。安裝套件、設定 Key、呼叫 API——三步驟完成。這篇教學會手把手帶你走完整個流程，每一步都有可以直接複製貼上的程式碼。

不管你是第一次用 AI API 的新手，還是從其他平台遷移過來的開發者，這篇都適合你。

想取得 OpenAI API？透過 CloudInsight 代購，免信用卡問題，享企業折扣與統一發票。

TL;DR

安裝 openai 套件 → 設定 API Key 環境變數 → 呼叫 client.chat.completions.create() 就完成。本教學涵蓋文字生成、多輪對話、Streaming、圖片分析、Function Calling，附完整可執行程式碼範例。

---

環境準備與 OpenAI SDK 安裝

Answer-First： 你需要 Python 3.8+、pip，以及一行 pip install openai 就能開始。

安裝步驟

# 建議使用虛擬環境
python -m venv openai-env
source openai-env/bin/activate  # macOS / Linux
# openai-env\Scripts\activate   # Windows

# 安裝 OpenAI SDK
pip install openai

驗證安裝：

python -c "import openai; print(openai.__version__)"

環境需求

項目	需求
Python	3.8 以上（建議 3.11+）
openai 套件	1.x 最新版
作業系統	Windows / macOS / Linux
網路	需要能連線到 api.openai.com

---

取得 API Key 與安全設定

Answer-First： 到 platform.openai.com 建立 API Key，用環境變數儲存，絕對不要寫死在程式碼裡。

建立 API Key

1. 登入 platform.openai.com
2. 點選左側選單「API Keys」
3. 點「Create new secret key」
4. 複製產生的 Key

完整的帳號註冊步驟，請參考 OpenAI API 註冊申請完整教學。

安全儲存 API Key

# macOS / Linux - 加入 ~/.bashrc 或 ~/.zshrc
export OPENAI_API_KEY="sk-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-key-here"

在 Python 中，SDK 會自動讀取 OPENAI_API_KEY 環境變數：

from openai import OpenAI

# 自動從環境變數讀取 API Key
client = OpenAI()

# 或者手動指定
client = OpenAI(api_key="sk-your-key-here")  # 不建議這樣做

安全提醒：

• 永遠不要把 API Key commit 到 Git
• 使用 .env 檔案要加到 .gitignore
• 正式環境用 Secret Manager（如 AWS Secrets Manager、GCP Secret Manager）

更完整的 API Key 安全管理規範，請參考 API Key 管理與安全最佳實踐。

---

文字生成：你的第一個 API 呼叫

Answer-First： 使用 client.chat.completions.create() 傳入模型名稱和 messages 陣列，就能取得 AI 的文字回應。

最簡單的呼叫

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "請用一句話解釋什麼是 API"}
    ]
)

print(response.choices[0].message.content)

就這樣。5 行有效程式碼。

使用 System Prompt 控制 AI 行為

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一位台灣的資深軟體工程師，用繁體中文回答，語氣輕鬆專業"},
        {"role": "user", "content": "什麼是 REST API？"}
    ],
    temperature=0.7,
    max_tokens=500
)

system 角色的訊息用來設定 AI 的行為模式。好的 System Prompt 可以大幅提升回應品質。

參數調整指南

參數	說明	建議值
temperature	創意程度（0-2）	翻譯 0.1，問答 0.7，創作 1.2
max_tokens	最大輸出長度	依需求設定，省錢就設小一點
top_p	取樣範圍	通常和 temperature 擇一調整
frequency_penalty	避免重複（0-2）	0.3-0.5 可減少重複

多輪對話

messages = [
    {"role": "system", "content": "你是一個友善的助手"},
    {"role": "user", "content": "Python 和 JavaScript 哪個比較適合新手？"},
]

response = client.chat.completions.create(model="gpt-4o", messages=messages)
assistant_reply = response.choices[0].message.content
print(assistant_reply)

# 繼續對話：把 AI 的回覆加回去
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "那如果我想做網站呢？"})

response = client.chat.completions.create(model="gpt-4o", messages=messages)
print(response.choices[0].message.content)

多輪對話的關鍵：每次呼叫時把完整的對話歷史都傳進去。AI 才能理解上下文。

但要注意——對話越長，Token 消耗越多。超過 Context Window 限制時需要截斷早期的對話。

透過 CloudInsight 採購 OpenAI API，享企業專屬折扣與統一發票。了解企業方案

---

Streaming 回應：即時顯示 AI 回覆

Answer-First： 加上 stream=True 參數，就能讓 AI 的回覆一個字一個字地即時顯示，大幅改善使用者體驗。

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "請介紹台灣 5 個最值得去的夜市"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

Streaming 在這些場景特別有用：

• 聊天機器人：使用者不用看著空白畫面等
• 長回覆：生成長文時，使用者可以提早開始閱讀
• 即時感：讓 AI 的回覆感覺更像真人對話

缺點是：Streaming 模式下你無法一次拿到 usage 資訊（Token 用量），需要額外設定 stream_options={"include_usage": True} 才能在最後一個 chunk 拿到。

---

圖片分析：Vision API 使用

Answer-First： GPT-4o 和 GPT-5 支援圖片輸入，只需在 messages 中加入圖片 URL 或 base64 編碼，就能讓 AI 理解圖片內容。

用 URL 傳送圖片

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "這張圖片裡有什麼？"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/photo.jpg"}
                }
            ]
        }
    ]
)

用 Base64 傳送本地圖片

import base64

with open("receipt.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "請辨識這張收據的金額"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}
                }
            ]
        }
    ]
)

實用場景：

• 收據/發票 OCR 辨識
• 產品圖片分類
• UI 截圖分析
• 圖表數據擷取

但要注意：圖片分析會消耗較多 Token。一張圖片大約相當於 85-1,700 Token，視解析度而定。

---

Function Calling：讓 AI 使用工具

Answer-First： Function Calling 讓你定義函式清單，AI 會判斷什麼時候該呼叫哪個函式並帶入正確參數，適合建置能查資料、操作系統的 AI Agent。

import json

# 定義工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "取得指定城市的即時天氣資訊",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名稱，例如：台北、東京"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "台北今天天氣如何？"}],
    tools=tools
)

# 檢查 AI 是否要呼叫函式
message = response.choices[0].message
if message.tool_calls:
    tool_call = message.tool_calls[0]
    function_name = tool_call.function.name
    arguments = json.loads(tool_call.function.arguments)
    print(f"AI 要呼叫：{function_name}({arguments})")

Function Calling 的流程：

1. 你定義好可用的函式清單
2. 使用者提問
3. AI 判斷是否需要呼叫函式
4. 如果需要，AI 回傳函式名稱和參數
5. 你在本地執行函式，取得結果
6. 把結果傳回給 AI，AI 用自然語言回覆使用者

---

錯誤處理與最佳實踐

Answer-First： 正式環境必須處理 Rate Limit（429）、Timeout、Invalid Request 等常見錯誤，搭配 exponential backoff 重試機制確保穩定性。

完整的錯誤處理範例

from openai import OpenAI, APIError, RateLimitError, APIConnectionError
import time

client = OpenAI()

def call_openai_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait_time = 2 ** attempt  # 1, 2, 4 秒
            print(f"超過速率限制，{wait_time} 秒後重試...")
            time.sleep(wait_time)
        except APIConnectionError:
            print("連線失敗，2 秒後重試...")
            time.sleep(2)
        except APIError as e:
            print(f"API 錯誤：{e}")
            raise
    raise Exception("重試次數已達上限")

常見錯誤

錯誤	原因	處理方式
RateLimitError (429)	請求太頻繁	Exponential backoff 重試
AuthenticationError (401)	API Key 無效	檢查 Key 是否正確
BadRequestError (400)	請求格式錯誤	檢查 messages 格式和參數
APIConnectionError	網路問題	檢查網路，稍後重試
InternalServerError (500)	OpenAI 伺服器問題	等待幾秒後重試

---

下一步：從範例到產品

你已經學會了 OpenAI API 的 Python 串接基礎。

接下來可以做什麼？

1. 嘗試不同模型：用 GPT-4o-mini 做簡單任務省錢，複雜任務再用 GPT-4o 或 GPT-5
2. 學習 Assistants API：建置更完整的 AI 助手
3. 了解成本控制：設定 Budget Limit，監控 Token 用量
4. 建置 RAG 系統：結合 Embeddings API 做知識庫問答

想了解 OpenAI API 的完整功能和企業方案，請參考 GPT-5 與 OpenAI API 完整指南。

如果你對 GPT-5 的能力和定價有更深的好奇，GPT-5 是什麼？最新功能與使用教學有更詳細的解析。如果你對 Google 的 AI API 也有興趣，Gemini API 完整開發指南是很好的比較參考。想看各家 API 的費用總整理，請參考 AI API 費用比較完整攻略。

需要企業級 OpenAI API 方案？CloudInsight 提供批量 Token 採購折扣、統一發票和中文技術支援。立即諮詢企業方案，或加入 LINE 官方帳號即時獲得技術支援。

常見問題 FAQ

Q1: OpenAI API 和 Azure OpenAI 差在哪？企業該選哪個？

兩者服務的模型相同但合約、部署、資料保護完全不同。(1) OpenAI API（api.openai.com）——直接跟 OpenAI 簽約、模型即時更新（新模型通常 OpenAI 官方先上）、定價透明、管理簡單、適合 startup / SaaS。但資料保護是 OpenAI 的 standard terms，合規認證相對少（SOC 2 Type 2 有，但部分大企業要求更多）。(2) Azure OpenAI——透過 Microsoft Azure 租借 OpenAI 模型、企業級合約、資料 residency 可選、HIPAA / FedRAMP High 認證、Microsoft 365 生態整合、有 Azure AD / IAM、可用 Azure policy 管理。缺點：(A) 新模型上架比 OpenAI 晚 2–8 週；(B) 需要申請 access（特別是 GPT-4o、o1 等）；(C) 定價和 OpenAI 一樣但稍複雜；(D) UI 比較 enterprise-style 不如 OpenAI direct 好用。選擇：(A) 個人 / startup → OpenAI API；(B) Microsoft 大客戶企業（已用 Azure AD、Office 365） → Azure OpenAI；(C) 金融 / 醫療 / 政府需要強合規 → Azure OpenAI（FedRAMP、HIPAA 覆蓋更全）；(D) 要最新模型 → OpenAI API；(E) 資料主權要求 → Azure OpenAI（可指定 region）。

Q2: OpenAI 的模型那麼多（GPT-4o、o1、o3、GPT-4.5、GPT-4 Turbo…），該怎麼選？

2025 年經驗法則。(1) 日常任務首選：GPT-4o 或 GPT-4o mini——速度快、便宜、多模態、適合 90% 用例。GPT-4o $2.50/$10.00 per 1M tokens，mini $0.15/$0.60 per 1M。(2) 需要 reasoning：o1 / o1-mini / o3——複雜推理、數學、coding 難題。o1 貴但效果顯著（每百萬 tokens $15/$60）。(3) 預算極緊：GPT-3.5 Turbo 或 GPT-4o mini——雖然品質差但便宜。(4) 特殊需求——(A) Realtime API：語音對話低延遲；(B) Whisper：語音轉文字；(C) TTS：文字轉語音；(D) DALL-E 3：圖片生成；(E) Embedding（text-embedding-3-small/large）：做 RAG。什麼時候用 o1 / o3：(A) 數學證明、複雜 coding（不是寫 boilerplate）、多步驟 planning；(B) 對結果正確性要求 > 速度和成本。什麼時候用 GPT-4o：(A) chatbot、內容生成、摘要、翻譯；(B) 需要速度（o1 很慢，平均 10–30 秒）；(C) 多模態（看圖、處理 audio）。不要用 GPT-4 Turbo ——已被 GPT-4o 取代，幾乎全面劣勢。開發建議：用 GPT-4o 開發原型，production 依實際情境 A/B test 決定 stick 還是升級 o1。

Q3: OpenAI 的「Assistants API」vs「Chat Completions API」差在哪？該用哪個？

Assistants API 是 stateful 抽象層，Chat Completions 是 stateless 原始 API。(1) Chat Completions API（/v1/chat/completions）——(A) 每次 request 你自己送完整 message history；(B) stateless；(C) 需要自己管對話記憶；(D) 功能核心：tools（function calling）、JSON mode、streaming；(E) 適合：你想完全控制 flow、已有自家 session 管理。(2) Assistants API（/v1/assistants）——(A) OpenAI 幫你管理 conversation thread；(B) 內建 tools：Code Interpreter（跑 Python）、File Search（RAG）、Function Calling；(C) 可以上傳檔案、assistant 自動引用；(D) 適合：chatbot、類 ChatGPT 產品、需要持久記憶。優劣比較：(A) 簡潔度：Assistants > Chat Completions（不用管 history）；(B) 彈性：Chat Completions > Assistants（你完全控制）；(C) 成本：Chat Completions 便宜（Assistants 的 thread storage、file search 都有額外費用）；(D) 偵錯：Chat Completions 容易（純 I/O），Assistants 抽象層多偵錯難。選擇：(A) 新手 / 快速做 chatbot → Assistants API；(B) 需要極致控制、成本優化 → Chat Completions；(C) 需要 Code Interpreter（跑 Python）或 File Search（RAG） → Assistants（自己做要花很多時間）；(D) 生產系統、需要複雜 flow → Chat Completions（雖然麻煩但可控）。注意：Assistants API 仍在 Beta，2025 可能有重大變動，production 要慎用。

Q4: OpenAI API 的費用怎麼控制？月帳單會爆炸嗎？

會爆炸，但有技巧防範。常見爆炸原因：(1) 迴圈呼叫——程式 bug 無限呼叫 API，一個下午燒 $1,000；(2) context 過長——對話累積到 20,000 tokens，每輪都付 $0.05；(3) 用錯模型——用 o1 做簡單任務（o1 貴 10 倍）；(4) 批次處理不用 Batch API——錯過 50% 折扣；(5) 沒設定 per-user quota——一個 user spam 整個月額度。控制策略（從簡單到進階）：(A) 設定 Hard Limit——OpenAI dashboard 可設每月最大支出，超過就 block；(B) Usage alerts——設 50% / 80% 告警 email；(C) 監控 tokens per request——log 每次呼叫的 input/output tokens，發現異常立刻檢查；(D) caching——相同 prompt 用 Redis cache 30 分鐘；(E) 用便宜的模型 fallback——先用 GPT-4o mini 試，品質不夠才升級 GPT-4o；(F) truncate history——對話超過 N 輪就只保留最近 10 輪 + summary；(G) Batch API——非即時任務用 batch，50% off；(H) prompt engineering 省 tokens——明確簡短 prompt 可省 30%+ tokens。實戰案例：某客戶月帳單 $5,000 → 優化後 $800：(1) GPT-4 Turbo → GPT-4o mini（$3,000 降到 $200）；(2) 加 Redis cache（省 40%）；(3) 非即時任務改 Batch API（又省 50%）。金額超過 $500/月 就該認真做成本管理。

Q5: 用 OpenAI API 做 production 產品，可用性（reliability）要怎麼保障？

多層備援 + 好的 error handling。OpenAI API 實際可用性：過去一年 SLA 約 99.5–99.8%，但有個別長時間 downtime（2024 年 6 月有 3 小時、11 月有 2 小時）。可用性策略：(1) Retry with exponential backoff——429 rate limit 和 5xx 都要 retry，至少 3 次；(2) Multi-provider fallback——主要用 OpenAI、fallback 到 Anthropic Claude 或 Google Gemini；可用 OpenRouter 或 LiteLLM 一個 API 多家切換；(3) Status page monitoring——subscribe status.openai.com，有 incident 馬上知道；(4) Circuit breaker pattern——連續失敗 5 次就 5 分鐘不打，避免 cascading failure；(5) 客戶端 timeout 設定——不要無限等，30 秒 timeout 合理；(6) 降級服務——OpenAI 掛掉時給使用者「AI 暫時無法使用，請稍後再試」而非白屏；(7) cache last-known-good——常見 query 的結果 cache 下來，API 掛時至少有基本回應。architect 實戰：(1) 在 LLM call 外包 wrapper function，所有 retry / fallback / logging 統一管理；(2) 用 OpenTelemetry 追蹤每個 API call 的 latency / error rate；(3) 設定 alerting：error rate > 5% 告警；(4) 預留 manual switch：緊急時可 dashboard 一鍵切 provider。Azure OpenAI 的優勢：有 99.9% SLA + 技術支援 + auto-failover across regions，高可用性需求選它。

---

參考資料

1. OpenAI — Python SDK Documentation（https://platform.openai.com/docs/libraries/python-library）
2. OpenAI — Chat Completions API Reference（https://platform.openai.com/docs/api-reference/chat）
3. OpenAI — Vision Guide（https://platform.openai.com/docs/guides/vision）
4. OpenAI Cookbook — GitHub（https://github.com/openai/openai-cookbook）

---