OpenAI SDK

OpenAI 官方 Python 和 TypeScript SDK 支援自訂 Base URL。將用戶端指向 https://api.agtcloud.cn/v1 後，可以使用相同的 SDK 方法呼叫 AGTCloud 的 Chat Completions 與 Responses 相容入口。

本頁適用於伺服器端應用程式。瀏覽器前端、桌面應用程式安裝套件和行動裝置程式碼無法安全儲存長期 API Key，不應直接建立帶有真實憑證的 OpenAI 用戶端。

選擇 Chat 還是 Responses

兩種入口使用相同的 AGTCloud API Key，但模型支援範圍可能不同。請在模型廣場確認模型支援的協議，並用完整模型 ID 替換範例中的 MODEL_ID。

準備工作

開始前，請確認已經：

• 在 API Keys 頁面建立 AGTCloud API Key；
• 準備支援 Chat Completions 或 Responses 的模型 ID；
• 使用 Python 3.10+ 或 Node.js 22+ 的可信任伺服器端執行環境；
• 為專案啟用相依性鎖定檔，不在正式環境中無控制地自動升級 SDK。

執行環境要求會隨 SDK 版本變化。升級 SDK 前，請同時核對目前官方支援範圍和專案的部署環境。

安裝 SDK

python -m pip install openai

安裝完成後，將實際解析出的 SDK 版本寫入專案鎖定檔。升級版本時，應重新驗證用戶端初始化、回應類型和 Streaming 處理邏輯。

設定 API Key

建議透過伺服器端環境變數提供 API Key。下面的設定僅作為安全預留位置範例，實際部署時可以改用雲平台金鑰服務。

export AGTCLOUD_API_KEY="your-api-key"

建立 OpenAI 用戶端

用戶端 Base URL 必須填寫 https://api.agtcloud.cn/v1。不要只填寫 API Origin，也不要繼續追加 /chat/completions 或 /responses；SDK 會根據呼叫的方法串接具體路徑。

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

使用 Responses

Responses 使用 input 表達文字或 Typed Items，成功回應包含狀態、Output Items 和 Token 用量。SDK 提供 output_text，用於彙整回應中的文字輸出。

response = client.responses.create(
    model="MODEL_ID",
    instructions="請使用簡潔、準確的中文回答。",
    input="用三點說明 API 彙整服務適合解決什麼問題。",
)

print(response.output_text)

output_text 適合讀取一般文字結果。需要處理函式呼叫、搜尋結果、推理項或其他類型時，應按順序遍歷 response.output，不能只保留 Message 類型。完整結構見 OpenAI Responses Reference。

使用 Chat Completions

Chat Completions 使用按順序排列的 messages。一般文字通常位於第一個 Choice 的 Assistant Message 中。

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "請使用簡潔、準確的中文回答。",
        },
        {
            "role": "user",
            "content": "用三點說明 API 彙整服務適合解決什麼問題。",
        },
    ],
)

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

如果模型傳回工具呼叫，message.content 可以為空，應改為檢查 message.tool_calls。欄位說明見 Chat Completions Reference。

接收串流輸出

OpenAI SDK 會把 SSE 回應暴露為可迭代事件流。Responses 的事件具有明確的 type；下例只列印文字增量，業務程式碼還應處理完成、失敗和中斷狀態。

stream = client.responses.create(
    model="MODEL_ID",
    input="請用一句話介紹你自己。",
    stream=True,
)

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

有狀態續接（需平台支援）

當模型、帳戶和上游管道支援回應儲存與續接時，可以儲存首輪回應，並把它的 ID 作為 previous_response_id 傳入下一次請求：

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="記住專案代號是 Aurora。",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="專案代號是什麼？",
)

print(second.output_text)

使用 previous_response_id 時，上一輪的 instructions 不會自動成為本輪指令。需要持續生效的行為約束，應在新請求中再次傳入。

如果目前呼叫鏈不支援回應儲存或續接，請由應用程式自行維護歷史，並在下一輪 input 中提交需要保留的 Input 與 Output Items。維護完整歷史時，不能只複製純文字，還需要保留業務所需的訊息、推理和工具呼叫關係。

逾時、重試與錯誤

OpenAI SDK 會將 HTTP 錯誤轉換為對應異常類型，並對部分連線錯誤、逾時、限流和伺服器端錯誤執行有限的自動重試。正式應用程式仍應根據請求類型明確設定逾時和重試上限，避免長時間等待或重複消耗。

不要在日誌中記錄完整 API Key、含敏感資料的請求體或未經處理的使用者內容。如果回應提供 Request ID，建議在錯誤日誌中儲存該識別碼，便於定位具體請求。

完成檢查

• 用戶端 Base URL 為 https://api.agtcloud.cn/v1，沒有重複 /v1，也沒有附加具體端點路徑。
• API Key 從可信伺服器端環境讀取，沒有進入前端程式碼或版本控制。
• MODEL_ID 已替換為目前 API Key 可見且支援目標入口的模型。
• 一般請求能夠正確讀取文字、狀態和用量。
• Streaming 程式碼能區分文字增量、完成事件和錯誤事件。
• 工具或多模態請求只向明確支援相應能力的模型傳送。

如果已有專案需要系統性替換服務供應商設定，請繼續閱讀原廠 SDK 移轉；需要將 Chat 結構重構為 Responses 時，參閱 Chat → Responses。