CGU AI Gateway V7

LLM API 呼叫教學

本頁整理 CGU LLM Gateway 的 OpenAI 相容呼叫方式。你可以用同一組 Base URL 與 API key 呼叫文字生成、串流、向量、圖片生成、依圖改圖、語音轉文字、語音翻譯、文字轉語音、Realtime WebSocket 與用量查詢。

請不要把 API key 寫進公開前端、HTML、Git、截圖或使用者可下載的檔案。下方範例一律使用 YOUR_CGU_API_KEY 佔位；正式系統建議由後端讀取環境變數後代為呼叫。

快速設定

Base URLhttps://air.cgu.edu.tw/cgullmapi/v1
AuthorizationAuthorization: Bearer YOUR_CGU_API_KEY
JSON 呼叫文字、向量、圖片生成、TTS 多數使用 Content-Type: application/json。
檔案上傳音訊上傳與依圖改圖使用 multipart/form-data，curl 範例用 -F。
WebSocketRealtime 使用 wss://air.cgu.edu.tw/cgullmapi/v1/...，不是一般 https:// POST。
模型清單每個帳號可用模型可能不同，請先呼叫 /v1/models 確認。
curl https://air.cgu.edu.tw/cgullmapi/v1/models \
  -H "Authorization: Bearer YOUR_CGU_API_KEY"

我該用哪一種呼叫方式？

一般文字、工具、Codex 或 Agent

POST /v1/responses

新專案優先使用。適合問答、摘要、推理、工具呼叫、程式產生、串流輸出與多步驟工作流程。

舊版聊天相容

POST /v1/chat/completions

給只支援 Chat Completions 的舊 SDK、Open WebUI、既有系統或第三方工具使用。

搜尋、RAG、相似度比對

POST /v1/embeddings

把文字轉成向量，用於資料庫檢索、文件比對、推薦、分類前處理。

圖片生成與依圖改圖

POST /v1/images/generationsPOST /v1/images/edits

文字生圖用 generations；上傳圖片後修改、重繪、套風格用 edits。

音訊

POST /v1/audio/transcriptionsPOST /v1/audio/translationsPOST /v1/audio/speech

transcriptions 是語音轉原語言文字；translations 是語音翻成英文；speech 是文字轉語音檔。

即時語音與低延遲互動

WS /v1/realtimeWS /v1/realtime/translationsWS /v1/realtime/transcription_sessions

需要 WebSocket。適合即時語音助理、即時翻譯、即時轉錄。

Responses API

建議新專案、Codex、agent workflow 優先使用 Responses API。它用 input 描述使用者輸入，回應文字可從 SDK 的 response.output_text 取得。

何時使用一般問答、摘要、程式協助、資料抽取、串流、工具型應用。
必要欄位model、input
常用欄位max_output_tokens 控制輸出長度；stream: true 開啟串流。
注意不是每個模型都同時支援 Responses 與 Chat Completions，實際請以 /v1/models 與測試結果為準。
curl https://air.cgu.edu.tw/cgullmapi/v1/responses \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "用一句話介紹長庚大學 AI 中心。",
    "max_output_tokens": 128
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CGU_API_KEY",
    base_url="https://air.cgu.edu.tw/cgullmapi/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    input="請用繁體中文列出三個 API 測試重點。",
    max_output_tokens=160,
)
print(response.output_text)

Streaming

串流適合前端逐字顯示、長回答、或需要降低等待感的介面。使用 curl 測試時請加 -N，避免 curl 緩衝輸出。

curl -N https://air.cgu.edu.tw/cgullmapi/v1/responses \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "請分三點說明反向代理的用途。",
    "stream": true,
    "max_output_tokens": 180
  }'

Chat Completions 相容呼叫

舊版 SDK、Open WebUI 或只支援 Chat Completions 的工具可使用這條路由。它使用 messages 陣列，常見角色是 system、user、assistant。

何時使用已有舊版 OpenAI chat 程式、Open WebUI、LangChain 舊流程、只接受 messages 格式的工具。
必要欄位model、messages
常用欄位max_completion_tokens、temperature、stream
注意Codex 類或新一代 agent 類模型可能只支援 /v1/responses，不一定支援 chat endpoint。
curl https://air.cgu.edu.tw/cgullmapi/v1/chat/completions \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "你是精簡的繁中助教。"},
      {"role": "user", "content": "回答 OK 並說明 API 已通。"}
    ],
    "max_completion_tokens": 128
  }'

Embeddings 文字向量

Embeddings 會把文字轉成數字向量。向量本身不是拿來閱讀的文字，而是給資料庫或程式做相似度搜尋、RAG 文件檢索、重複內容偵測、分類與推薦。

何時使用把文件切段後建立索引、依使用者問題找相關段落、做語意搜尋或相似度比對。
必要欄位model、input
input 格式可以是一段字串，也可以是多段字串陣列。大量資料請分批送出。
常用模型text-embedding-3-small、text-embedding-3-large，或帳號被授權的本地 embedding 模型。
curl https://air.cgu.edu.tw/cgullmapi/v1/embeddings \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "CGU LLM Gateway 測試文字",
      "這段文字會被轉成向量"
    ]
  }'

Images 圖片生成與依圖改圖

圖片功能分成兩種：文字生圖使用 /images/generations；依照上傳圖片修改、重繪、換風格、補圖使用 /images/edits。目前測試中 chatgpt-image-latest、gpt-image-1、gpt-image-1-mini、gpt-image-1.5、gpt-image-2 皆曾通過圖片生成與改圖測試；實際可用模型以你的帳號 /v1/models 為準。

文字生成圖片

只提供文字 prompt，模型會產生新圖片。適合 icon、插圖、海報草圖、視覺概念圖。

curl https://air.cgu.edu.tw/cgullmapi/v1/images/generations \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chatgpt-image-latest",
    "prompt": "A clean blue square icon with CGU letters on a white background",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }'

依圖改圖

上傳一張圖片，再用 prompt 說明要怎麼改。請使用 multipart，上傳欄位名稱是 image。

curl https://air.cgu.edu.tw/cgullmapi/v1/images/edits \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -F model=chatgpt-image-latest \
  -F image=@input.png \
  -F prompt="保留主體構圖，改成乾淨的藍白科技風格 icon" \
  -F size=1024x1024
圖片 API 通常會回傳 JSON，內含圖片資料或圖片 URL。請依回傳格式在後端解碼或下載後再交給前端顯示。

Audio 語音轉文字、翻譯、文字轉語音

語音轉文字 STT

使用 /audio/transcriptions，上傳音檔後回傳原語言逐字稿。適合會議紀錄、訪談、課程錄音、語音輸入。

curl https://air.cgu.edu.tw/cgullmapi/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -F model=gpt-4o-mini-transcribe \
  -F language=zh \
  -F response_format=json \
  -F file=@meeting.wav

語音翻譯

使用 /audio/translations，上傳非英文音檔後翻譯成英文文字。若你要保留原語言，請用 transcriptions。

curl https://air.cgu.edu.tw/cgullmapi/v1/audio/translations \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -F model=whisper-1 \
  -F response_format=json \
  -F file=@speech.wav

文字轉語音 TTS

使用 /audio/speech，送入文字後回傳音訊 bytes。請用後端呼叫並把音檔交給前端播放或下載。

curl https://air.cgu.edu.tw/cgullmapi/v1/audio/speech \
  -H "Authorization: Bearer YOUR_CGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "voice": "alloy",
    "input": "今天是很適合完成 API 串接的一天。",
    "instructions": "請用自然清楚的語氣朗讀。",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Realtime WebSocket

Realtime 需要 WebSocket，適合低延遲語音、即時對話、即時翻譯或即時轉錄。若經過外部反向代理，請確認有轉發 Upgrade: websocket、Connection: Upgrade 與相關 WebSocket header。

/realtime一般即時多模態對話。常用模型如 gpt-realtime-2。
/realtime/translations即時翻譯工作流。常用模型如 gpt-realtime-translate。
/realtime/transcription_sessions即時轉錄工作流。常用模型如 gpt-realtime-whisper。
測試重點HTTP 101 Switching Protocols 代表 WebSocket 握手成功；完整 session 測試還應等待伺服器事件並送入音訊或文字事件。
const ws = new WebSocket(
  "wss://air.cgu.edu.tw/cgullmapi/v1/realtime?model=gpt-realtime-2",
  [],
);

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: { instructions: "請用繁體中文回覆。" }
  }));
});

ws.addEventListener("message", (event) => {
  console.log(JSON.parse(event.data));
});
瀏覽器原生 WebSocket 不容易附加 Authorization header。正式產品建議由後端建立 Realtime 連線，或由後端發放短效 token / session，再交給前端使用。

用量與計費查詢

/v1/me/usage 會回傳目前 API key 綁定帳號的 local 與 OpenAI 用量、token 配額、OpenAI 美金配額與剩餘額度。建議在大量測試前後各查一次，確認請求是否有正確計入用量。

curl https://air.cgu.edu.tw/cgullmapi/v1/me/usage \
  -H "Authorization: Bearer YOUR_CGU_API_KEY"

常見問題

401API key 遺失、格式不是 Bearer token，或 key 不存在。
403模型未被允許、串流被停用，或 OpenAI token / USD 配額已用完。
404路由不支援，或該模型不在此端點可用。
413請求太大或超過單次 token 限制。
415 / 422常見於 multipart 欄位錯誤，例如音訊欄位不是 file，或改圖欄位不是 image。
426Realtime 用一般 HTTP 打到 WebSocket 端點，請改用 WS/WSS。
模型不支援端點同一個模型不一定支援所有 endpoint。例如 Codex 類模型通常應走 Responses；圖片模型應走 Images；語音模型應走 Audio。
Brotli / brGateway 會對上游送 Accept-Encoding: identity，並移除回應中的 Content-Encoding 與 Content-Length，避免客戶端拿到已解壓內容但仍標示 br 的錯誤。

Codex 使用教學

請妥善保管 CGU API Key。API Key 通常會以 sk- 開頭，請不要公開、截圖分享或貼到公開網站。

一、完全關閉 Codex App

已使用過 Codex 的使用者，請先在 Codex App 中登出原本帳號，接著關閉 Codex App。

Windows 額外確認請檢查螢幕右下角工作列通知區域是否仍有 Codex 小圖示。若有，請在圖示上按右鍵並選擇 Exit 或關閉，確保 Codex 已完全退出。

二、啟用並複製 CGU API Key

步驟 3：進入 CGU API Key 頁面請開啟以下網址，啟用並複製你的 CGU API Key：
https://air.cgu.edu.tw/workspace4/LLMAPI/index.php
API Key 格式API Key 通常會以 sk- 開頭，例如：sk-xxxxxxxxxxxxxxxxxxxxxxxx

三、找到 Codex 設定資料夾

Windows 路徑請將 YourUserName 改成你自己的 Windows 使用者名稱。
C:\Users\YourUserName\.codex\
macOS 路徑請將 YourUserName 改成你自己的 macOS 使用者名稱。可在 Finder 按下 Command + Shift + G 後輸入路徑。
/Users/YourUserName/.codex/

四、修改 config.toml

請在 Codex 設定資料夾中找到或建立 config.toml，並加入以下設定：

model_provider = "custom"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

[model_providers.custom]
name = "CGU API"
base_url = "https://air.cgu.edu.tw/cgullmapi/v1"
requires_openai_auth = true
wire_api = "responses"

保留舊專案設定的建議

如果 config.toml 中已經有 [projects] 區塊，建議只取代 [projects] 以上的內容，不要刪除 [projects] 以下原本的專案設定。如果不需要保留舊設定，也可以直接用上述內容取代整個 config.toml。

五、重新啟動Codex App

六、依據提示輸入CGUAPIKEY