排查 API 與 MCP 接入

區分 API Key 和 OAuth，定位權限與檔案傳輸問題，並在不繞過支出保護的前提下處理報價或不確定請求。

正式版最後核實 2026-08-31

本頁目錄

使用正確地址和憑據

整合方式	地址	鑑權
公開 API	`https://api.animgen.com/v1`	帶適當 Scope 的 Bearer API Key
官方遠端 MCP	`https://api.animgen.com/mcp`	相容 Streamable HTTP 客戶端中的 OAuth
工具清單	`https://animgen.com/mcp/tools.json`	公開文件，不是 MCP 連線端點

MCP 已上線公開測試。瀏覽器未帶 OAuth 直接開啟 MCP URL 時，可能收到鑑權響應；它不是普通 HTML 頁面。僅憑這一點不能判斷服務不可用。

不要用 API Key 替代 MCP OAuth，不要把網頁登入 Token 當作 API Key，也不要自行加 /sse 路徑。按 MCP 客戶端接入配置。

檢查所登入的 AnimGen 帳戶是否已驗證、開發者訪問是否暫停，以及是否授予所需 Scope；產生費用的生成還要檢查點數餘額。

授權被撤銷、權限缺失或客戶端授權流程不相容，都需要單獨處理，不是增加餘額就能解決。必要時通過官方流程重新連線，不要為了繞過錯誤停用 PKCE 或放寬回撥校驗。

首先使用 list_models 做只讀檢查。它成功只能證明連線與讀權限正常，不能證明客戶端可以上傳檔案、使用者已批准生成，或完整輸出質量已驗收。

遠端服務不能讀取本地路徑。呼叫 prepare_image_upload 後，必須用獲准的客戶端能力傳輸真實位元組，再通過 complete_image_upload 獲得可用檔案 ID。

同樣，download_asset 返回的是後設資料和臨時 URL，不是已經儲存到電腦的檔案。下載位元組時不要轉發 API/OAuth 憑據。客戶端缺少相關能力時，應說明限制，使用獲准且受支援的替代方式。

錯誤碼	下一步
`SPEND_CONFIRMATION_REQUIRED`	取得具體批准並提供必需保護引數
`QUOTE_EXPIRED`	重新報價並核對更新後的金額
`QUOTE_MISMATCH` / `QUOTE_CHANGED`	核對引數或價格變化，再請求批准
`QUOTE_ALREADY_USED`	找回原操作，不把原報價用於新任務
`CREDIT_LIMIT_EXCEEDED`	停止，縮小請求或詢問是否批准新上限
`INSUFFICIENT_CREDITS`	說明餘額問題，不自動購買

quote_id 和 max_credits 是 MCP 中與 request 同級的工具引數，不是公開 API 請求體欄位。單次上限也不是整個會話總預算。詳見支出保護。

保留相同請求、冪等鍵、帳戶及憑據身份：API 對應 Key ID，MCP 對應 OAuth 客戶端。不能換 Key 或客戶端後，仍假定冪等去重會跟隨。

已知任務 ID 時先輪詢，再決定是否重試建立。遵守可重試標誌及 API 返回的 Retry-After；MCP 結構化錯誤不保證攜帶這個 HTTP 響應頭。為重試和本地等待設上限。

本地超時不會取消遠端任務；終態失敗也可能有部分輸出和收費。求助時，通過私密渠道提供請求/任務 ID、時間、錯誤碼、客戶端型別和失敗階段，不附帶憑據或簽名連結。

允許文件互動分析

不收集搜尋字詞、程式碼或自由文字。此開關僅控制文件互動事件。隱私權政策