mathruffian-dot/opencode-lazy-packs/09-groq-api

把 API 變成自己的工具（Groq）

官方文件查證日期：2026-07-27

依據：<https://console.groq.com/docs/speech-to-text>、<https://console.groq.com/docs/api-reference>、<https://console.groq.com/docs/rate-limits>、<https://console.groq.com/docs/models>、<https://console.groq.com/docs/your-data>、<https://console.groq.com/docs/billing-faqs>、<https://console.groq.com/docs/quickstart>

🔴 先看這裡：隱私紅線（這一段是本包最重要的內容）

這一包做的每一件事，都會把你的聲音檔送到別人的伺服器上。

不是「處理完就消失」那種送，是整個音檔上傳、在美國的機器上跑完、再把文字傳回來。你電腦上的麥克風錄到什麼，就送出去什麼。

這三類錄音，一律不要上傳

順便三條也不要：唸到學生姓名的點名錄音、學生口說測驗的作答錄音、任何你不確定裡面有誰在講話的檔案。

這些可以上傳

• 你自己一個人講課、備課、口述的錄音（只有你的聲音）
• 你自己的公開演講、研習分享
• 你自己錄的旁白、口播稿
• 公開影片（新聞、公播教材、你自己頻道的影片）

一句話的判斷標準

## 🔴 「這個音檔如果明天出現在網路上，會不會有人受傷？會不會需要通報？」

只要答案是「會」或「不確定」——不上傳。沒有例外，不看時間趕不趕。

⚠️ 最容易出事的地方：檔案結尾

課堂錄音最常見的意外不是內容，是「忘記按停止」。

你以為錄的是自己講課的 40 分鐘，實際上錄音一直開到下課、開到學生跑上來問問題、開到你跟隔壁老師聊完。

🔴 規矩：上傳前先跳到檔案的最後 30 秒聽一遍。

這一步花 30 秒，可以擋掉這一包 90% 的真實風險。

Groq 官方的資料政策（查證 2026-07-27）

講完紅線再講政策，順序不能反——政策再好，也不會讓紅線消失。

建議研習前先做一件事：登入 Console → Settings → Data Controls → 開啟 Zero Data Retention。花 10 秒，之後所有請求都適用。

🔴 但是——開了 ZDR，紅線一條都不會消失。

政策是廠商的承諾，不是「你的檔案沒有離開過你的電腦」的技術保證。

中間還有網路、還有你的電腦、還有你等一下會不會把 srt 檔傳到 LINE 群組。

真正安全的做法只有一個：那個檔案根本不要上傳。

真的非處理不可怎麼辦

有些內容就是不能上雲端，但你又真的需要逐字稿。三條路：

1. 請當事人自己來：讓學生／家長自己用手機的語音輸入打字，你只收文字
2. 本機跑：在自己電腦上跑離線的語音辨識模型（不連網、不上傳）。這條不在本研習範圍，也不在本包
3. 不做：這是完全合理的選項。省下的 20 分鐘，遠遠比不上一次個資事件

這一包在研習裡的位置：作品⑤「把 API 變成自己的工具」

第三天上午。這一包做的是「內部工具」——只有你自己在電腦上用，還不碰網頁。

前面幾包是「把別人做好的東西接進來」（NotebookLM、Obsidian、Supabase）。這一包不一樣：

你會拿一個原始的 API，做出一個以後可以一直用的東西。

這是整套研習裡第一次「呼叫外部服務、拿回結果、包成工具」。學會這個模式，之後接任何服務都是同一套邏輯。

🔑 這一包成不成功，判斷標準只有一個

所以步驟六（包成 Skill）不是加分題，是這一包的正題。 前面五個步驟都只是為了搞清楚「那句人話背後要做什麼」。

📌 下午的 10-netlify 會把這個工具再往外推一層：變成一個網頁，讓別人也能用。

今天上午先把「自己能用」做穩，下午才有東西可以搬上網。

這一包會幫你做什麼

兩條主線，都用同一把金鑰：

A 線的產物剛好是 B 線的原料。合起來就是：一段錄音 → 一份講義。

🚨 這一包的四個陷阱（先看完再動手）

陷阱 ① 是最花時間的一個——網路上 95% 的 Whisper 教學都是寫給 OpenAI 的，那邊有 srt，Groq 沒有。 你會以為自己打錯字。

免費方案（不用綁信用卡）

⚠️ 以下為 2026-07-27 查到的數字。服務商隨時會調整，以官方頁面為準（本節最後教你怎麼自己查）。

要不要綁卡

🔴 研習現場的規矩：整個過程不會有任何畫面要你輸入卡號。

只要看到要求付款方式的畫面，代表你走進了升級流程——按上一頁退出來，不要輸入。

這一包主線完全不需要 Developer 方案。

免費額度（Whisper 語音）

⚠️ 「最低計費 10 秒」這條會咬人。

意思是：再短的檔，也至少吃掉 10 秒額度。

所以「把一堂課切成 200 個小片段各自送一次」是最浪費的做法——200 個 3 秒的檔會被算成 2,000 秒。

正確做法：切大段（10 分鐘一段），不要切小段。

（付費的 Developer 方案單檔上限是 100 MB。本包不走那條，寫在這裡只是讓你看到別人的教學寫 100 MB 時不會困惑。）

免費額度（文字模型，B 線用）

🚨 這裡有一個沒人講、但一定會撞到的坑：

「每分鐘 token」小得驚人。 一小時的中文演講逐字稿大約 9,000～12,000 字，換算下來遠遠超過 12,000 token 的每分鐘上限。

也就是說：你不可能把一整份逐字稿一次丟給它清洗。 一定會拿到 429。

解法：分段送。 步驟五的小程式已經內建分段（預設一段 1,200 字）和自動重試，照著跑就好。

怎麼自己查最新的（模型會改名、額度會變）

📌 本包刻意不寫任何價格。 免費方案用不到，而寫死的價格只會在半年後變成錯誤資訊。

模型名稱也一樣：如果下面哪個模型名在你跑的時候不存在了，先跑上面那行 `/v1/models` 看它改叫什麼，不要硬套本文件。

選哪個 Whisper 模型：研習主線用 whisper-large-v3

註：作者的 audio-to-srt 與 youtube-workflow 技能預設用 whisper-large-v3-turbo（求速度，word-level 時間碼一樣有）。兩者都能用，本包的推薦理由見下。

Groq 上目前有兩個（查證 2026-07-27）：

🔴 推薦：whisper-large-v3。理由是一個很多人沒注意到的事實——

在免費方案下，這兩個模型的額度完全一樣（都是 20 次/分、7,200 音訊秒/小時、28,800 音訊秒/日）。

turbo 的賣點是「比較便宜」。但免費方案本來就不用錢，所以那個賣點在這裡等於零。

而速度差多少？189 倍 vs 216 倍。一支 30 分鐘的錄音，一個要 9.5 秒、一個要 8.3 秒。你根本感覺不到。

結論：免費用戶沒有任何理由選 turbo。用準的那個。

什麼時候才換 turbo：你要一次跑幾十個檔、而且真的坐在旁邊等；或者以後升級成付費、開始在意費用。

📌 關於繁體中文的表現：Groq 官方沒有公布任何中文專屬的準確度數字，Whisper 官方也只有整體多語數字。

本包推薦 whisper-large-v3 的依據是「整體錯字率較低」＋「免費方案額度相同」，不是任何中文的實測比較。

實際上兩個模型對台灣國語的表現都算堪用，主要問題不是聽錯字，是專有名詞（人名、地名、課本術語）和繁簡——這兩件事都靠步驟五的清洗解決，換模型幫助不大。

選哪個文字模型：主線用 llama-3.3-70b-versatile

⚠️ 模型名稱會改。跑之前先用 /v1/models 確認一次（見上方「怎麼自己查最新的」）。

🤔 等一下——文字清洗為什麼不直接叫 OpenCode 做就好？

這是研習現場一定會有人問的問題，而且問得很對。

你已經在 01-connect-model 幫 OpenCode 接了模型。要清洗逐字稿，把檔案丟給它說「幫我整理成講義」，它就做完了。幹嘛還要多申請一把 Groq 金鑰、多寫一支程式？

答案是三件事：

💡 所以：日常自己用，直接叫 OpenCode 清洗完全 OK，不必每次都走 API。

但這一包要你走一次 API，是為了讓你手上有一個「離開 OpenCode 也能跑」的東西。

先備條件

• [ ] 已完成 `00-env-setup` 與 `01-connect-model`
• [ ] 已完成 `02-file-toolkit` 的 B 段（要用 ffmpeg 和 ffprobe 壓縮、切檔、量長度）
• [ ] 建議完成 `07-github`（金鑰不外洩這件事在那一包有完整說明）
• [ ] 有網路
• [ ] 手上有一份符合上面隱私紅線的音訊或影片檔

驗證：

ffmpeg -version; ffprobe -version

兩個都印出版本 = 過。

⚠️ `ffprobe` 常常缺席。 如果只裝了 yt-dlp 自帶的那套 FFmpeg，ffprobe 可能不在 PATH 上。

補裝系統版：winget install --id Gyan.FFmpeg -e（沒有管理員權限就加 --scope user）。

mac：brew install ffmpeg／Linux：sudo apt install -y ffmpeg。

真的裝不起來也還有救——步驟四的小程式有備援做法，看那一節。

📁 先建一個工作資料夾，名字用英數字

New-Item -ItemType Directory -Force "$HOME\Documents\groq-subtitle"

🚨 資料夾和檔名先不要用中文。

Windows 的命令列（PowerShell 5.1）傳中文檔名給 ffmpeg、curl 時偶爾會變亂碼，你會看到「找不到檔案」但檔案明明就在。

做法：轉檔前先把來源改成 `lesson01.mp4` 這種名字，全部跑完再改回中文。

這一條看起來很瑣碎，但研習現場每一梯都有人卡在這裡半小時。

步驟一：申請 Groq 金鑰

🖐️ 全程在瀏覽器手動做。AI agent 不要代為註冊、不要代填任何欄位。

1-1 註冊

1. 開 <https://console.groq.com>
2. 選 Continue with Google 或 Continue with GitHub（建議用 07-github 那個 GitHub 帳號，之後好管理），也可以用 Email
3. 沒有等待清單、不用審核、不會問你要信用卡

1-2 建立金鑰

左側選單 API Keys → Create API Key → 取一個看得懂的名字（例如 研習-字幕工具）→ 建立。

🔴 金鑰只會完整顯示這一次。

關掉視窗之後看不到第二次，只能刪掉重產一把。

現在就複製起來，貼到你的密碼管理器（不是貼到記事本、不是貼到 LINE 給自己）。

金鑰長得像 gsk_ 開頭的一長串。

1-3 順手開啟 Zero Data Retention

Settings → Data Controls → 開啟 Zero Data Retention。

10 秒的事，之後所有請求都適用。（再說一次：開了它，前面那些紅線一條都不會消失。）

1-4 驗證：金鑰是活的嗎

先做完步驟二設定好環境變數，再回來跑這一行（步驟二的驗證裡有）。

步驟二：金鑰要放哪裡（🚨 這一步做錯，金鑰會上 GitHub）

🔴 三條絕對規則

① 金鑰不寫進任何 `.md` 檔案裡 —— 包含你等一下要做的那個 Skill 檔。

② 金鑰不寫進任何會被 `git add` 的檔案裡。

③ 金鑰不貼進聊天視窗（包含貼給 AI agent 看）。

理由：研習的設定檔會投影在大螢幕上、會被拍照；而 GitHub 上有機器人專門在掃新推上去的金鑰，掃到的速度比你發現的速度快。

主線做法：設成環境變數（推薦，整台電腦設一次）

環境變數的好處是：金鑰不存在於任何一個檔案裡，所以永遠不可能被 commit。

Windows（PowerShell）

[System.Environment]::SetEnvironmentVariable("GROQ_API_KEY", "貼上你的金鑰", "User")

設完一定要重開終端機（連 OpenCode 也要完全關掉重開），新的環境變數才會生效。

macOS / Linux（寫進 ~/.zshrc 或 ~/.bashrc，然後 source 一次）

echo 'export GROQ_API_KEY="貼上你的金鑰"' >> ~/.zshrc
source ~/.zshrc

驗證（🔴 這行刻意不印出金鑰本身，可以安心投影）

Windows

if ($env:GROQ_API_KEY) { "KEY_SET len=" + $env:GROQ_API_KEY.Length } else { "KEY_MISSING" }

macOS / Linux

if [ -n "$GROQ_API_KEY" ]; then echo "KEY_SET len=${#GROQ_API_KEY}"; else echo "KEY_MISSING"; fi

看到 KEY_SET len=<某個數字> = 過。看到 KEY_MISSING → 沒重開終端機，或變數名打錯。

驗證金鑰是活的

curl.exe https://api.groq.com/openai/v1/models -H "Authorization: Bearer $env:GROQ_API_KEY"

• 回傳一大段 JSON（裡面看得到 whisper-large-v3）→ ✅ 金鑰可用，順便看到現在有哪些模型
• 回 invalid_api_key → 金鑰複製時少了一截，或前後有多餘的空白，重複製一次

Windows 一定要打 curl.exe（有 .exe），否則會叫到 PowerShell 內建的別名，行為完全不同。

專案做法：.env ＋ .gitignore（下午的 10-netlify 會用到）

如果你的工具要放進一個「會推上 GitHub 的專案資料夾」，用 .env：

先建 `.gitignore`（🔴 先建這個，再建 `.env`，順序不能反）

.env
*.key
credentials.*
desktop.ini
*.tmp

再建 `.env`

GROQ_API_KEY=貼上你的金鑰

驗證 `.env` 真的被擋掉了：

git status --short

🔴 輸出裡出現 `.env` 就是失敗——代表 git 還看得到它，下一次 git add . 就會把金鑰送上 GitHub。

回頭檢查 .gitignore 是不是拼錯、是不是放在 repo 根目錄。

更嚴格的檢查（agent 請跑這一行）：

git check-ignore -v .env

有輸出（會告訴你被 .gitignore 第幾行擋掉）= ✅ 過。沒有輸出 = ❌ 沒擋到。

📌 關於 Google 雲端硬碟：.env 放在雲端硬碟資料夾裡會被同步到你的雲端帳號——這通常可以接受（那是你自己的帳號）。

但它跟 `.gitignore` 是兩回事，雲端同步不會擋 git。兩件事都要做。

如果你要在 opencode.json 裡引用金鑰

本包用不到這件事（我們是自己呼叫 API，不是把 Groq 接成 OpenCode 的模型供應商）。但萬一你之後要：

"environment": { "GROQ_API_KEY": "{env:GROQ_API_KEY}" }

🔴 寫 `{env:GROQ_API_KEY}`，不要寫實際那串字。

這是 00-env-setup 附錄「MCP 通用守則」第 5 條的規矩，本包完全沿用。

🚨 萬一金鑰不小心外流了

刪掉檔案、刪掉訊息、清掉 git 歷史——全部沒有用。 金鑰已經在別人手上了。

## 唯一有效的處置：回 Console → API Keys → 把那把金鑰刪掉，重新產一把。

這件事做完之前，其他都不用做。做完之後，記得把環境變數也換成新的。

步驟三：A 線 — 把聲音變成字幕（.srt）

A1. 先把檔案壓小（🚨 這裡處理陷阱 ②）

免費方案單檔上限 25 MB。一支手機錄的 30 分鐘影片動輒好幾百 MB，直接送一定被打回。

官方建議的做法：降到 16kHz 單聲道、轉成 FLAC。 這樣做不會影響辨識準確度——Whisper 本來就只吃 16kHz，多出來的取樣率和第二個聲道，送上去也是被丟掉。

Groq 官方文件給的指令（原封不動）：

ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a flac "clean.flac"