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"

模型目錄

以下是目前開放給所有人的模型。把模型名稱照表填進請求的 model 欄位即可;你的帳號實際能用哪些,以 /v1/models 為準。

模型分兩種額度,各自計算:學校算力池(Spark)與本地模型扣「本地模型 Token 額度」,不花美元;OpenAI 模型扣「OpenAI 成本額度」(美元)。OpenAI 額度用完時,仍可改用學校算力池模型。剩餘額度請到 API Key 頁面查看。

學校算力池(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 成本額度(美元)

用途模型呼叫端點
文字、推理、Codexgpt-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=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=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.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.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 額度」,不花美元額度。

GitHubhttps://github.com/anomalyco/opencode
官方網站與文件https://opencode.ai/docs
opencode 會讀寫專案裡的檔案、也會執行指令。請在要處理的專案資料夾裡啟動,重要的修改前先用 Git 備份。不要使用 /share:它會把對話上傳成公開連結。

一、安裝 opencode

Windows先安裝 Node.js(LTS 版),再在 PowerShell 或命令提示字元執行 npm install -g opencode-ai。也可以用 choco install opencode 或 scoop install opencode。
macOSbrew install anomalyco/tap/opencode,或 curl -fsSL https://opencode.ai/install | bash
Linuxcurl -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。
步驟 3Provider 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。