LLM API 呼叫教學
本頁整理 CGU LLM Gateway 的 OpenAI 相容呼叫方式。你可以用同一組 Base URL 與 API key 呼叫文字生成、串流、向量、圖片生成、依圖改圖、語音轉文字、語音翻譯、文字轉語音、Realtime WebSocket 與用量查詢。
YOUR_CGU_API_KEY 佔位;正式系統建議由後端讀取環境變數後代為呼叫。快速設定
| Base URL | https://air.cgu.edu.tw/cgullmapi/v1 |
|---|---|
| Authorization | Authorization: Bearer YOUR_CGU_API_KEY |
| JSON 呼叫 | 文字、向量、圖片生成、TTS 多數使用 Content-Type: application/json。 |
| 檔案上傳 | 音訊上傳與依圖改圖使用 multipart/form-data,curl 範例用 -F。 |
| WebSocket | Realtime 使用 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"模型目錄
以下是目前開放給所有人的模型。把模型名稱照表填進請求的 model 欄位即可;你的帳號實際能用哪些,以 /v1/models 為準。
學校算力池(Spark)模型|扣本地模型 Token 額度
學校自己的 GPU 伺服器,支援 /v1/chat/completions 與 /v1/responses,也可以接 opencode 寫程式。
| 模型 | 適合拿來做什麼 | 可輸入 |
|---|---|---|
gpt-oss-120b | 一般問答、推理分析、寫程式;opencode 的預設模型。 | 文字 |
gemma-4-26b-a4b-it | 一般問答、摘要與翻譯;長文件;看圖片(截圖、圖表、照片)。 | 文字、圖片 |
mistral-small-4-119b-2603 | 寫程式、需要呼叫工具的多步驟工作(agent)、整理資料;長文件;看圖片。 | 文字、圖片 |
nemotron-3-super-120b-a12b | 需要多想一下的問題:推理、數學、程式除錯;長文件。 | 文字 |
文字範例
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-oss-120b",
"messages": [
{"role": "user", "content": "用一句話介紹長庚大學。"}
]
}'看圖範例(Python)
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_CGU_API_KEY",
base_url="https://air.cgu.edu.tw/cgullmapi/v1",
)
with open("photo.png", "rb") as f:
image = base64.b64encode(f.read()).decode()
response = client.chat.completions.create(
model="gemma-4-26b-a4b-it",
messages=[{"role": "user", "content": [
{"type": "text", "text": "請描述這張圖片。"},
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
]}],
)
print(response.choices[0].message.content)OpenAI 模型|扣 OpenAI 成本額度(美元)
| 用途 | 模型 | 呼叫端點 |
|---|---|---|
| 文字、推理、Codex | gpt-6-luna(建議使用,費率只有 gpt-5.6-luna 的一半)、gpt-5.6-luna | /v1/responses、/v1/chat/completions |
| 文字向量 | text-embedding-3-small、text-embedding-3-large | /v1/embeddings |
| 圖片生成、依圖改圖 | gpt-image-2、gpt-image-1.5、gpt-image-1、gpt-image-1-mini、chatgpt-image-latest | /v1/images/generations、/v1/images/edits |
| 語音轉文字、語音翻譯 | whisper-1 | /v1/audio/transcriptions、/v1/audio/translations |
| 文字轉語音 | gpt-4o-mini-tts、tts-1、tts-1-hd | /v1/audio/speech |
| 即時語音(WebSocket) | gpt-realtime-2.1、gpt-realtime-2.1-mini、gpt-realtime-2、gpt-realtime-mini、gpt-realtime-translate、gpt-realtime-whisper | 見下方 Realtime |
其他費率較高的 OpenAI 模型目前暫停開放,鎖定清單請看 API Key 頁面。
本地模型(Ollama)|扣本地模型 Token 額度
| 模型 | 用途 | 呼叫端點 | 說明 |
|---|---|---|---|
gpt-oss:20b | 文字對話 | /v1/chat/completions | 簡單的問答與短文字處理。 |
bge-m3:latest | 文字向量(多語) | /v1/embeddings | 向量長度 1024。 |
translategemma:latest | 翻譯 | /v1/chat/completions | 把要翻譯的文字直接放進訊息,例如「Translate into English: 長庚大學」。 |
模型閒置一段時間後,第一次呼叫要先載入,會等比較久。要看圖片請用上方學校算力池的 gemma-4-26b-a4b-it 或 mistral-small-4-119b-2603。
我該用哪一種呼叫方式?
一般文字、工具、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.6-luna",
"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.6-luna",
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.6-luna",
"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.6-luna",
"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(扣 OpenAI 成本額度);本地的 bge-m3:latest(扣本地模型 Token 額度)。 |
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=1024x1024Audio 語音轉文字、翻譯、文字轉語音
語音轉文字 STT
使用 /audio/transcriptions,上傳音檔後回傳原語言逐字稿。適合會議紀錄、訪談、課程錄音、語音輸入。
curl https://air.cgu.edu.tw/cgullmapi/v1/audio/transcriptions \
-H "Authorization: Bearer YOUR_CGU_API_KEY" \
-F model=whisper-1 \
-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.mp3Realtime 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));
});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"常見問題
| 401 | API key 遺失、格式不是 Bearer token,或 key 不存在。 |
|---|---|
| 403 | 模型未被允許、串流被停用,或 OpenAI token / USD 配額已用完。 |
| 404 | 路由不支援,或該模型不在此端點可用。 |
| 413 | 請求太大或超過單次 token 限制。 |
| 415 / 422 | 常見於 multipart 欄位錯誤,例如音訊欄位不是 file,或改圖欄位不是 image。 |
| 426 | Realtime 用一般 HTTP 打到 WebSocket 端點,請改用 WS/WSS。 |
| 模型不支援端點 | 同一個模型不一定支援所有 endpoint。例如 Codex 類模型通常應走 Responses;圖片模型應走 Images;語音模型應走 Audio。 |
| Brotli / br | Gateway 會對上游送 Accept-Encoding: identity,並移除回應中的 Content-Encoding 與 Content-Length,避免客戶端拿到已解壓內容但仍標示 br 的錯誤。 |
Codex 使用教學
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.6-luna"
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
opencode 使用教學(學校算力池模型)
opencode 是開源的 AI 程式助理,在終端機裡幫你讀程式、改檔案、執行指令。接上本服務後可以使用學校算力池(Spark)的模型,只扣「本地模型 Token 額度」,不花美元額度。
| GitHub | https://github.com/anomalyco/opencode |
|---|---|
| 官方網站與文件 | https://opencode.ai/docs |
/share:它會把對話上傳成公開連結。一、安裝 opencode
| Windows | 先安裝 Node.js(LTS 版),再在 PowerShell 或命令提示字元執行 npm install -g opencode-ai。也可以用 choco install opencode 或 scoop install opencode。 |
|---|---|
| macOS | brew install anomalyco/tap/opencode,或 curl -fsSL https://opencode.ai/install | bash |
| Linux | curl -fsSL https://opencode.ai/install | bash |
二、在專案資料夾建立 opencode.json
在你的專案資料夾(要讓 opencode 處理的那個資料夾)新增檔案 opencode.json,內容如下。這個檔案不含金鑰,可以放進 Git。
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"cgu": {
"npm": "@ai-sdk/openai-compatible",
"name": "CGU API",
"options": {
"baseURL": "https://air.cgu.edu.tw/cgullmapi/v1"
},
"models": {
"gpt-oss-120b": { "name": "gpt-oss-120b(學校算力池)", "limit": { "context": 131072, "output": 32768 } },
"gemma-4-26b-a4b-it": { "name": "gemma-4-26b-a4b-it(學校算力池)", "limit": { "context": 262144, "output": 32768 } },
"mistral-small-4-119b-2603": { "name": "mistral-small-4-119b-2603(學校算力池)", "limit": { "context": 262144, "output": 32768 } },
"nemotron-3-super-120b-a12b": { "name": "nemotron-3-super-120b-a12b(學校算力池)", "limit": { "context": 262144, "output": 32768 } }
}
}
},
"model": "cgu/gpt-oss-120b"
}想讓所有專案都用這個設定,macOS/Linux 也可以放在 ~/.config/opencode/opencode.json。
三、輸入 CGU API Key(只要做一次)
| 步驟 1 | 在專案資料夾開啟終端機,輸入 opencode 啟動。 |
|---|---|
| 步驟 2 | 輸入 /connect,在服務清單拉到最下面選 Other。 |
| 步驟 3 | Provider ID 輸入 cgu(要和 opencode.json 裡的 "cgu" 一樣)。 |
| 步驟 4 | 貼上你的 CGU API Key(sk- 開頭)。金鑰存在 opencode 自己的設定裡,不會寫進 opencode.json。 |
四、開始使用
直接用中文描述要做的事,例如「幫我看這個專案的結構」「這個錯誤怎麼修」。預設模型是 gpt-oss-120b,輸入 /models 可以切換。第一次在專案裡使用,可以先輸入 /init,讓它整理一份專案說明(AGENTS.md)。改壞了可以用 /undo 復原上一步。
gpt-oss-120b | 預設推薦:一般的讀程式、寫程式、除錯都適合。 |
|---|---|
gemma-4-26b-a4b-it | 專案很大、需要一次讀很多檔案時;也能看截圖。 |
mistral-small-4-119b-2603 | 步驟比較多的修改,例如一次改好幾個檔案再執行測試;也能看截圖。 |
nemotron-3-super-120b-a12b | 比較難的除錯、演算法或邏輯問題。 |
gpt-oss:20b)目前不支援 opencode 需要的「工具呼叫」(讀檔、執行指令),請用上表的模型。要用 OpenAI 的模型寫程式,請用上方的 Codex。