跳至主要内容

常見問題

先從 API 呼叫與用戶端設定確認基本連線，再處理具體錯誤。

API 呼叫​

如何確認 API Key 複製完整​

Key 建立後通常只完整顯示一次。複製後先貼到本機安全位置，檢查前後沒有空格、換行或中文引號；之後看不到完整值時不要猜，直接停用舊 Key 並重新建立。

我應該先測軟體，還是先測 curl​

先測 curl。它只包含位址、Key、模型與請求內容，可以先排除用戶端快取、外掛設定和環境變數繼承問題。

為什麼 curl 可以，軟體不可以​

優先檢查軟體中的 Provider 類型、Base URL 層級、API Key 與 Model 欄位，然後建立新會話或重啟軟體。

Base URL 和完整 Endpoint 有什麼不同​

Base URL 是協定根，軟體會繼續附加路徑；完整 Endpoint 已包含具體介面路徑。

模型清單為什麼是空的​

許多用戶端不會自動取得第三方模型清單。只要 Key 和 Base URL 正確，就能從模型與價格頁複製 YOUR_MODEL 手動填入。

如何判斷帳戶狀態或額度不足​

如果請求回傳 403 或 429，且 Key、模型與路徑都確認無誤，請回到主站查看帳戶狀態、額度與目前模型可用狀態。不要依公開文件中的舊截圖判斷。

用最小請求定位問題​

先固定位址、Key、模型與請求內容，只送出一則短訊息。若 curl 成功，問題通常在用戶端設定或舊會話；若仍失敗，再依 HTTP 狀態碼進入「錯誤修復」。

用戶端與本機環境​

找不到命令​

  • 現象： 軟體或終端通常會顯示「找不到命令」，也可能是設定已儲存但請求仍失敗。
  • 原因： 終端找不到 claude、codex 或 gemini 命令，通常是安裝目錄不在 PATH，或舊終端尚未刷新環境。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 重新開啟終端並執行版本命令；仍失敗時依官方來源重新安裝，不要從未知鏡像下載。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

環境變數沒有生效​

  • 現象： 軟體或終端通常會顯示「環境變數沒有生效」，也可能是設定已儲存但請求仍失敗。
  • 原因： 變數設定在一個終端視窗裡，軟體卻從另一個舊視窗、桌面捷徑或背景程序啟動。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 在啟動軟體的同一個終端列印變數確認，設定後關閉舊會話並重新開啟。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

儲存設定後仍請求預設服務​

  • 現象： 軟體或終端通常會顯示「儲存設定後仍請求預設服務」，也可能是設定已儲存但請求仍失敗。
  • 原因： 用戶端可能快取舊 Provider，或目前會話沒有切換到新設定。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 建立新會話或重啟用戶端，確認目前 Provider、Base URL、Key 和模型都來自 PopGo 設定。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

模型不可用​

  • 現象： 軟體或終端通常會顯示「模型不可用」，也可能是設定已儲存但請求仍失敗。
  • 原因： 模型 ID 拼寫、存取範圍或即時可用狀態發生變化。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 從模型與價格頁重新複製模型 ID，並先用最小請求驗證；不要依舊截圖手打。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

npm 全域安裝權限錯誤​

  • 現象： 軟體或終端通常會顯示「npm 全域安裝權限錯誤」，也可能是設定已儲存但請求仍失敗。
  • 原因： Windows 可能缺少安裝權限；macOS/Linux 可能因 Node.js 安裝方式導致全域目錄不可寫入。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： Windows 請重新開啟具有安裝權限的 PowerShell；macOS/Linux 優先依官方建議或套件管理器重新安裝 Node.js，不要長期依賴 sudo npm install -g。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

Claude Code 要求登入官方帳號​

  • 現象： 軟體或終端通常會顯示「Claude Code 要求登入官方帳號」，也可能是設定已儲存但請求仍失敗。
  • 原因： 環境變數沒有被 Claude Code 讀取，工具因此回到官方登入流程。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 在同一個終端確認 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，關閉舊視窗後重新啟動，並執行 claude doctor。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

Codex 出現驗證錯誤​

  • 現象： 軟體或終端通常會顯示「Codex 出現驗證錯誤」，也可能是設定已儲存但請求仍失敗。
  • 原因： 本機設定讀不到 POPGO_API_KEY，或 config.toml 中的 Provider 名稱、model_provider 和 env_key 不一致。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 確認環境變數名稱嚴格為 POPGO_API_KEY，再檢查 model_provider = popgo 與 model_providers.popgo 是否對應。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

填入 Base URL 後回傳 404​

  • 現象： 軟體或終端通常會顯示「填入 Base URL 後回傳 404」，也可能是設定已儲存但請求仍失敗。
  • 原因： 軟體可能會在填入的位址後繼續附加路徑，造成 /v1/v1 或完整 Endpoint 重複。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 回到快速開始頁的 Base URL 層級表：Base URL 欄位填協定根，只有完整 Endpoint 欄位才填完整路徑。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

憑證或 SSL 錯誤​

  • 現象： 軟體或終端通常會顯示「憑證或 SSL 錯誤」，也可能是設定已儲存但請求仍失敗。
  • 原因： 常見原因是本機代理、公司網路攔截、系統時間錯誤或憑證鏈異常。
  • 自查：
    1. 在啟動軟體的同一個終端確認命令、環境變數與實際設定。
    2. 關閉舊會話與舊程序後重新啟動，排除快取與環境繼承問題。
    3. 依快速開始頁的 Base URL、Key 與模型範例逐項比較。
  • 處理： 不要關閉 TLS 驗證。先校準系統時間，暫時停用本機代理或更換網路驗證，再檢查安全軟體是否攔截 HTTPS。
  • 驗證： 重新啟動用戶端後送出短訊息；正常回應且設定一致才算恢復。

參考音訊和輸出聲音有何差別？​

generate_audio只控制輸出音軌，不證明參考音訊支援。名稱依能力顯示影片／音訊、僅影片或僅音訊。參考影片模式必須有影片，純音訊模式必須有音訊。

為何C有參考音訊卻無參考影片？​

C明確排除影片輸入，影片上限0不能以留空繞過；參考音訊最多3個。Kling音訊描述未公布參考輸入欄位，所以暫不開放；Grok也不支援。

貼上網路素材就一定保留公開來源嗎？​

明確HTTP(S)直鏈會保留；只複製二進位資料仍是本機。生成素材僅保留sourceUrl時標為公開。點標籤可看來源，但公開不保證服務可讀；不支援Base64的模型需要可讀URL。

為何有任務ID但素材無效果？​

ID只證明接受。檢查模式、發出欄位、下載及成片；首幀不同於普通參考圖。被忽略的錯誤欄位仍可能生成及計費。詳見影片任務流程及模型頁。

建議排查順序​

  1. 先記錄完整錯誤：HTTP 狀態碼、請求路徑、用戶端名稱與發生時間。
  2. 用快速開始頁的最小 curl 請求重現，確認問題來自 Key、模型、位址或用戶端。
  3. 一次只修改一個變數；修復後先驗證短文字請求，再恢復串流、工具呼叫或媒體參數。