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 官方帳號即時獲得技術支援。

---

參考資料

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）

---