← 返回

如何透過 OpenAI 相容 API 呼叫模型

2026-11-11

摘要

串接 OpenAI 相容 API 時，先設定服務商的 API 金鑰、基礎網址（base URL）與正確的模型 ID，再呼叫 Chat Completions 端點傳送對話請求。本篇提供 Python 和 cURL 範例，帶你完成首次呼叫、接收串流回應並排除常見錯誤，也說明圖片、影片和語音生成各自適用的端點。

要透過 OpenAI 相容 API 呼叫模型，先在 OpenAI 用戶端設定服務商的 API 金鑰和基礎網址（base URL），再指定正確的模型 ID，向 Chat Completions 端點傳送對話請求。不使用 SDK 時，也能用 cURL 傳送相同的請求，只要提供 Bearer 驗證、JSON 格式的訊息清單與模型識別碼。

先傳送一則簡短的文字請求，確認能收到回答，再加入串流輸出或應用程式需要的選項。不要一開始就同時加入工具、圖片和長篇對話，這樣更容易找出設定錯誤。

1. 正確設定三個連線參數

OpenAI 相容 API 採用 OpenAI API 的請求與回應格式，但服務由各服務商提供。使用 OpenAI SDK 不代表請求一定會傳給 OpenAI；請求送往哪個服務，取決於你設定的基礎網址。在 AIAdapter 支援的對話模型之間切換時，可以沿用同一個用戶端和同一帳戶的 API 金鑰，將連線設定與模型選擇分開管理。

AIAdapter 的 API 文件規定了以下設定：

SDK 會在基礎網址後附加 /chat/completions。保留 /v1，不要把完整端點填入 base_url。

從模型廣場選擇聊天模型。以下範例使用已列出的 Qwen3.5-Plus 模型，識別碼為 aliyun-bailian/qwen3.5-plus。請完整複製，不要只填寫 Qwen 這類模型家族名稱。

在 Console → API Keys 中建立金鑰，並將它存放在伺服器端的環境變數或機密管理服務中，不要寫入前端 JavaScript。呼叫 AIAdapter 時須使用 AIAdapter 金鑰進行驗證，不能以 OpenAI 帳戶金鑰替代。

2. 準備 Python 與環境變數

目前的 OpenAI Python SDK 要求 Python 3.10 或更新版本。使用執行指令碼的同一個直譯器安裝：

python -m pip install --upgrade openai

在終端機設定以下環境變數，將範例中的金鑰替換成你的帳戶金鑰。

macOS、Linux 或 Bash：

export AIADAPTER_API_KEY="your-aiadapter-api-key"
export AIADAPTER_MODEL_ID="aliyun-bailian/qwen3.5-plus"

Windows PowerShell：

$env:AIADAPTER_API_KEY = "your-aiadapter-api-key"
$env:AIADAPTER_MODEL_ID = "aliyun-bailian/qwen3.5-plus"

這些環境變數只在目前的終端機工作階段生效。請從同一個終端機啟動 Python，確保程式能讀取這些變數。部署應用程式時，在代管平台的機密設定中設定環境變數。避免在共用電腦上輸入金鑰，以免指令歷史紀錄洩漏金鑰。

3. 傳送第一則聊天請求

將以下範例儲存為 call_model.py：

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["AIADAPTER_API_KEY"],
    base_url="https://api.aiadapter.com/v1",
    timeout=60.0,
    max_retries=0,
) as client:
    completion = client.chat.completions.create(
        model=os.environ["AIADAPTER_MODEL_ID"],
        messages=[
            {"role": "user", "content": "Explain an API in two sentences."}
        ],
    )
    print(completion.choices[0].message.content)

執行 python call_model.py。

SDK 會自動建立驗證標頭並序列化請求。messages 用來傳入對話內容，model 指定要呼叫的模型。一般文字回應的回答位於 choices[0].message.content，指令碼會將它印出。

首次請求未加入可選的取樣、推理和輸出長度限制欄位。基本呼叫成功後，再依所選模型的文件加入這些欄位。有些模型使用 max_tokens，其他模型則使用 max_completion_tokens 或不同的控制參數。

max_retries=0 會停用 SDK 自動重試，方便排除首次呼叫的問題。timeout=60.0 將網路操作的逾時時間設為 60 秒，不代表整個指令碼必須在 60 秒內執行完畢。正式上線時，應依應用程式需求設定逾時時間，並限制重試次數。

4. 用 cURL 傳送等效請求

使用以下 Bash 命令，不經過 Python SDK，直接測試 HTTP 請求：

curl https://api.aiadapter.com/v1/chat/completions \
  -H "Authorization: Bearer $AIADAPTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aliyun-bailian/qwen3.5-plus",
    "messages": [
      {"role": "user", "content": "Explain an API in two sentences."}
    ]
  }'

這裡需要填寫完整端點，因為 cURL 不會像 SDK 一樣附加路徑。-d 選項會傳送 POST 請求。讀取回傳的 JSON；如果請求失敗，也要查看其中的錯誤訊息。

如果 cURL 成功而 Python 失敗，檢查環境變數、已安裝的 SDK 和實際用戶端設定。如果兩者都失敗，先排查金鑰、端點、模型 ID 和帳戶餘額，再修改提示詞。

5. 接收串流回應，逐步顯示回答

對於支援串流輸出的聊天模型，設定 stream=True，並從每個資料區塊的 delta.content 中讀取文字。將下面的範例儲存為獨立指令碼，使用相同的環境變數：

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["AIADAPTER_API_KEY"],
    base_url="https://api.aiadapter.com/v1",
    timeout=60.0,
    max_retries=0,
) as client:
    with client.chat.completions.create(
        model=os.environ["AIADAPTER_MODEL_ID"],
        messages=[{"role": "user", "content": "Explain an API in two sentences."}],
        stream=True,
    ) as stream:
        for chunk in stream:
            if chunk.choices:
                text = chunk.choices[0].delta.content
                if text:
                    print(text, end="", flush=True)
    print()

AIAdapter 文件說明，串流聊天回應使用 Server-Sent Events。程式碼中的檢查會略過不含新增文字的資料區塊，包括控制區塊或僅含用量資訊的區塊。串流輸出會逐步傳遞結果，但不會改變模型的輸入要求。

6. 擴充功能前，先排除呼叫錯誤

結合 HTTP 狀態碼和回傳的錯誤訊息找出問題：

在 Python 中，捕捉 openai.APIStatusError 後可檢查 status_code 和 response。連線失敗則捕捉 openai.APIConnectionError。串流回應中的錯誤也可能引發 openai.APIError，因此除了建立請求時，也要在逐一讀取串流資料的過程中處理例外。不要把金鑰和敏感提示詞寫入診斷日誌。

常見問題

OpenAI 相容是否代表所有 OpenAI 端點都能使用？

不代表。能使用哪些端點，取決於服務商實際支援哪些操作。本篇使用 Chat Completions，因為 AIAdapter 文件明確列出這個端點。SDK 也可能提供 Responses、檔案上傳、助理等資源，但函式庫有這些方法，不代表服務商也支援對應功能。請選用與服務商文件一致的 SDK 方法。加入進階對話功能前，先核對所選模型接受的工具、推理和結構化輸出欄位，再把它們加入已能正常執行的請求。

切換模型時，可以不修改這個 Python 用戶端嗎？

如果另一個模型也使用相同的 Chat Completions 端點和驗證方式，就能保留用戶端，只更換模型 ID。指令碼會從 AIADAPTER_MODEL_ID 讀取模型 ID，因此修改設定即可選擇另一個對話模型。切換後，仍須檢查新模型支援的參數、上下文長度限制與回應處理方式。先用相同的簡短訊息確認能正常呼叫，再恢復應用程式中的工具、格式限制或較長的對話紀錄。

這個對話範例也能生成圖片或影片嗎？

請依照要生成的內容，選擇對應的 API 操作。AIAdapter 文件列出 /v1/images/generations 用於圖片生成、/v1/video/generations 用於影片任務、/v1/audio/speech 用於語音合成。生成影片時，須先提交任務，再輪詢 /v1/video/generations/{id} 取得狀態。能理解圖片的視覺語言模型，與用來生成圖片的模型並不相同。每種操作都應搭配對應模型的請求欄位和結果處理方式，不能只把影片模型 ID 填入對話範例。

重試會如何影響失敗或逾時的呼叫？

OpenAI Python SDK 預設會針對部分連線錯誤和 HTTP 錯誤重試兩次。本篇在首次測試時停用自動重試，方便找出失敗原因。請求逾時不代表伺服器端未處理請求；重複提交生成請求，可能導致重複執行。應限制重試次數，查看可取得的請求或任務狀態，並將額外嘗試納入用量和成本考量。若串流連線在傳回部分文字後中斷，也要另外處理已收到的部分結果。

如何確認首次請求的成本？

呼叫前，先在模型價格一覽與對應模型的詳細頁面查看目前的費率和計費單位。以 token 計費的對話請求，須同時考慮輸入和輸出用量；選用的欄位與回答長度也可能影響用量。若回應提供用量資訊，請與控制台的帳單紀錄核對。圖片、影片和語音生成可能使用不同的計費單位，不能直接用對話模型的 token 單價估算成本。

先用一則簡短請求確認能收到回答，再沿用成功的設定擴充功能。還沒有 API 金鑰的話，可以先建立帳戶，開始在伺服器端串接。

aliyun-bailian/qwen3.5-plus

常見問答

如何透過 OpenAI 相容 API 呼叫模型

串接 OpenAI 相容 API 時，先設定服務商的 API 金鑰、基礎網址（base URL）與正確的模型 ID，再呼叫 Chat Completions 端點傳送對話請求。本篇提供 Python 和 cURL 範例，帶你完成首次呼叫、接收串流回應並排除常見錯誤，也說明圖片、影片和語音生成各自適用的端點。