OpenAI API 調用教學（Python）：安裝 SDK、第一個請求與常見報錯

本文根據 OpenAI 開發者文檔（Quickstart、SDKs、Text generation、Streaming、Error codes）和 openai-python 官方倉庫 README 整理，資料核對於 2026-10-07。代碼裏的模型名會隨官方更新而變化，請以 Models 頁面 為準。

適用於誰

• 會一點 Python，想寫出第一段調用 OpenAI 模型的代碼的人；
• 照着網上舊教學寫代碼，發現寫法和現在的官方 SDK 對不上、運行就報錯的人；
• 想知道報錯時先查哪裏的人。

結論先說

1. 準備：Python 3.10 及以上；一個 API Key（獲取方法見 /guides/openai-api-key），並設為環境變量 OPENAI_API_KEY。
2. 安裝：pip install openai。
3. 最小代碼：client = OpenAI() → client.responses.create(model=..., input=...) → print(response.output_text)。官方現在推薦新項目用 Responses API；老的 Chat Completions 仍然可用。
4. 報錯先看狀態碼：401 是密鑰問題，429 要區分「請求太快」和「餘額 / 限額用完」，APIConnectionError 是網絡連不上。

步驟

1. 建一個乾淨的環境並安裝 SDK

bash
python -m venv .venv
# macOS / Linux 激活：source .venv/bin/activate
# Windows 激活：.venv\Scripts\activate
pip install openai

裝完可以用 python -c "import openai; print(openai.__version__)" 查看版本。README 提醒：升級後看不到新功能，多半是當前環境還在用舊版本。

2. 配置密鑰

官方 SDK 會自動讀取環境變量 OPENAI_API_KEY，所以代碼裏不需要也不應該寫密鑰。

• macOS / Linux：export OPENAI_API_KEY="你的密鑰"
• Windows PowerShell：setx OPENAI_API_KEY "你的密鑰"，然後重新打開終端

如果習慣用 .env 文件，README 推薦配合 python-dotenv 加載，並把 .env 加進 .gitignore，避免密鑰進到代碼倉庫。

3. 發出第一個請求

新建 example.py：

python
from openai import OpenAI

client = OpenAI()  # 自動讀取環境變量 OPENAI_API_KEY

response = client.responses.create(
    model="gpt-6-astra",  # 2026-10 官方 Quickstart 使用的模型，可換成其他模型
    instructions="你是一位說話簡潔的中文助手。",
    input="用兩句話解釋什麼是 API。",
)

print(response.output_text)

運行 python example.py，幾秒後會打印模型回答。幾個參數的意思：

• model：模型 ID。Models 頁面把 GPT-6 Astra 列為複雜推理和編程的旗艦，GPT-6.1 Sol 兼顧能力和成本，GPT-6 Luna 適合注重成本、大批量的任務。模型會更新換代，以頁面為準。
• instructions：高層級的行為要求（語氣、角色、規則），優先級高於 input 裏的內容。
• input：可以是一段字符串，也可以是帶 role 的消息列表。
• output_text：SDK 提供的便捷屬性，把所有文字輸出拼成一個字符串。官方提醒 output 數組裏經常不止一項（還有推理、工具調用等），不要硬寫 output[0].content[0].text。

4. 看這次用了多少 token

python
print(response.usage.input_tokens, response.usage.output_tokens, response.usage.total_tokens)

Responses API 的用量字段是 input_tokens / output_tokens / total_tokens（Chat Completions 叫 prompt_tokens / completion_tokens）。推理模型的內部推理 token 不顯示成文字，但按輸出 token 計費，所以回答很短、用量卻不小是正常的。費用怎麼算見 /guides/openai-api-pricing-billing。

5. 流式輸出（邊生成邊顯示）

做聊天介面時，加 stream=True，然後按事件類型取文字增量：

python
from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-6-astra",
    input="寫一首四行的小詩，主題是秋天。",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print()

Responses 的流式返回是帶類型的事件，常用的有 response.created、response.output_text.delta、response.completed 和 error。

6. 加上錯誤處理

python
import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(model="gpt-6-astra", input="你好")
    print(response.output_text)
except openai.AuthenticationError:
    print("401：密鑰無效或已被刪除，檢查 OPENAI_API_KEY")
except openai.RateLimitError as e:
    print("429：", e.code, e.message)  # 先看 code 判斷是限速還是餘額/限額問題
except openai.APIConnectionError:
    print("連不上 API：檢查網絡、防火牆或證書設定")
except openai.APIStatusError as e:
    print("其他錯誤：", e.status_code, e.request_id)

SDK 預設會對連接錯誤、408、409、429 和 5xx 自動重試 2 次（短暫的指數退避），可以用 OpenAI(max_retries=0) 關掉或改次數；預設超時是 10 分鐘，可以用 timeout= 調整。

常見報錯速查

排查時記下返回的 request ID（SDK 裏是 response._request_id，出錯時是 e.request_id），聯絡官方支持時會用到。

常見問題

Q：還能用 client.chat.completions.create 嗎？

可以。README 說明 Chat Completions 會長期支持；但官方建議新項目用 Responses API。兩者的區別和遷移方法見 /guides/openai-responses-api。

Q：想先不寫代碼、在網頁上試效果？

用 OpenAI Playground，見 /guides/openai-playground。注意 Playground 的調用同樣計入 API 用量和費用。

Q：異步怎麼寫？

把 OpenAI 換成 AsyncOpenAI，每次調用前加 await，其餘參數一樣。

Q：能把密鑰直接寫在 OpenAI(api_key="...") 裏嗎？

技術上可以，但官方不推薦：代碼一旦分享或上載倉庫，密鑰就泄露了。

參考資料

• OpenAI 開發者文檔：Developer quickstart — https://developers.openai.com/api/docs/quickstart
• OpenAI 開發者文檔：SDKs and CLI — https://developers.openai.com/api/docs/libraries
• openai-python 官方倉庫 README — https://github.com/openai/openai-python
• OpenAI API Reference：Create a response — https://developers.openai.com/api/reference/resources/responses/methods/create
• OpenAI 開發者文檔：Text generation — https://developers.openai.com/api/docs/guides/text
• OpenAI 開發者文檔：Streaming API responses — https://developers.openai.com/api/docs/guides/streaming-responses
• OpenAI 開發者文檔：Error codes — https://developers.openai.com/api/docs/guides/error-codes
• OpenAI 開發者文檔：Models — https://developers.openai.com/api/docs/models
• OpenAI 幫助中心：Reviewing API usage and costs — https://help.openai.com/en/articles/10478918-reviewing-api-usage-and-costs