OpenAI API 呼叫範例：Chat Completions 實戰

本文你將得到什麼？

在已完成《OpenAI API 申請》的前提下，學會：

• 用 HTTP 頭攜帶 API Key
• 傳送一條對話補全請求
• 解析回覆並處理常見錯誤
• 了解串流輸出的基本形態

官方文件：https://platform.openai.com/docs/
控制台：https://platform.openai.com/

下列模型名與路徑請以文件當前版本為準，範例側重「可執行的結構」。

1. 用 curl 快速驗證

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是簡潔的中文助手。"},
      {"role": "user", "content": "用三句話介紹什麼是 API。"}
    ],
    "temperature": 0.4
  }'

成功時回應中會包含 choices[0].message.content 欄位。把完整 JSON 保存一次，方便對照欄位含義。

2. Python 最小範例

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是嚴謹的技術寫作者。"},
        {"role": "user", "content": "列出呼叫 OpenAI API 前的 5 條安全檢查。"},
    ],
    temperature=0.3,
)

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

安裝 SDK 前請閱讀官方 Docs 的安裝說明；版本更新時注意 breaking changes。

3. 訊息角色怎麼用？

role	用途
system	全域風格、安全邊界、輸出格式
user	當前使用者請求
assistant	歷史助手回覆（多輪時回傳）

多輪時把歷史按順序拼接，但注意上下文長度與費用；過長對話應摘要壓縮。

4. 錯誤處理骨架

import time
from openai import RateLimitError, APIError

def chat_with_retry(client, **kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            # 記錄 status／request id，便於工單排查
            raise
    raise RuntimeError("重試耗盡")

5. 串流輸出入門

適合聊天 UI 逐字展示：

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "寫一首關於除錯的短詩"}],
    stream=True,
)

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

6. 生產環境建議

1. Key 僅存伺服器端金鑰庫／環境變數
2. 對使用者輸入做長度與敏感內容策略控制
3. 記錄 request id、模型名、耗時、token 用量
4. 為 Prompt 建設定中心，避免魔術字串
5. 設定預算告警，防止異常迴圈呼叫

網頁端體驗仍可透過 ChatGPT 完成；產品資訊見 OpenAI。

7. 常見報錯速查

現象	可能原因	處理
401	Key 無效	重新產生並檢查環境變數
429	速率／配額	退避重試或降並行
逾時	網路或不穩定代理	換網路、加逾時與重試
輸出截斷	max tokens 過小	提高上限或要求更短輸出

若必須經代理存取，評估穩定性與合規；鏡像站入口 僅為佔位，不建議未經評估直接用於生產。

小結

先 curl 打通鑑權，再封裝 Python／Node 用戶端，最後補齊重試、日誌與串流。把《API 申請》裡的金鑰治理與本文的呼叫範本結合，即可開始真正的產品整合。更多細節持續以官方 Docs 為準。