1. 金鑰與費用
到「API 與 MCP」建立金鑰，選擇必要權限、1–365 天有效期及累計提交點數上限。完整金鑰只顯示一次，可隨時撤銷。預設唯讀；生成需要 jobs:write。
與網站共用錢包；送單凍結、完成扣點、確認失敗或取消後退回。金鑰的累計提交上限包含失敗與取消的訂單，不會隨退點恢復。撤銷不會取消已送出的任務。
每把金鑰每分鐘最多 60 次請求（REST 與 MCP 合計）。收到 429 請依 Retry-After 等待。金鑰只放後端或安全的 MCP 設定，切勿放公開前端／Git／對話中。
2. REST API
Base URL：https://aivideo.com.tw/api/v1；每次帶 Authorization: Bearer <API Key>。
curl https://aivideo.com.tw/api/v1/jobs -H "Authorization: Bearer $NETFOX_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: image-demo-001" -d '{"taskType":"image_generation","inputPayload":{"prompt":"A red fox in a sunny garden","aspectRatio":"1:1"}}'成功收單回 HTTP 202 與 id。每 15 秒 GET /jobs/:id，直到 success、failed 或 cancelled。識別碼請每次新作品換新值；重試必須沿用同一把金鑰、相同識別碼與原始參數。識別碼相同但參數不同回 409。
| 路徑 | 權限 | 用途 |
|---|---|---|
| GET /capabilities | 有效金鑰 | 可用功能、底價、輸入欄位；實際點數隨參數變動 |
| GET /wallet | wallet:read | 可用／凍結額度 |
| POST /jobs | jobs:write | 生成；必填 Idempotency-Key（8–128 英數 . _ : -） |
| GET /jobs | jobs:read | 本人最近 50 筆作品 |
| GET /jobs/:id | jobs:read | 進度、文字結果與資產清單 |
| POST /jobs/:id/cancel | jobs:write | 請求取消；確認停止才退點 |
| POST /assets | assets:write | multipart 的 file 欄位，最多 20 MB |
| GET /assets/:id/content | assets:read | 下載本人素材或產物（二進位） |
素材先上傳，再把回傳的 reference（例如 asset:xxx）填入 imageUrl / imageUrls / audioUrl 等欄位。不接受外部 URL、私人網路位址或其他帳號的資產。下載需同樣帶金鑰，downloadPath 不是公開分享連結。
curl https://aivideo.com.tw/api/v1/assets -H "Authorization: Bearer $NETFOX_API_KEY" -F "[email protected]" # 回傳 reference: asset:... # 以圖生圖： { "taskType": "image_img2img", "inputPayload": { "imageUrl": "asset:...", "prompt": "Watercolor portrait", "faceConsent": true } }
人臉素材需本人或已取得當事人同意，才可設 faceConsent: true。可用功能以 capabilities 為準；故事整片／分段重拍／2K 專用加購目前仍在網站操作，不在通用 v1 API。
錯誤：400 參數錯誤、401 無效／過期／撤銷金鑰、402 錢包不足、403 權限或金鑰上限、404 非本人／不存在、409 重試內容不同、429 速率限制、5xx 暫時故障。網路中斷或 5xx 時不可自行換識別碼重送。
3. 遠端 MCP（Streamable HTTP）
網址：https://aivideo.com.tw/api/mcp。支援自訂 Bearer Header 的 MCP client 可直接連線，不需要 npm 套件或網站帳密。以下是支援 url / headers 設定的客戶端範例：
{
"mcpServers": {
"netfox": {
"url": "https://aivideo.com.tw/api/mcp",
"headers": {
"Authorization": "Bearer <你的 API Key>"
}
}
}
}工具：netfox_capabilities、netfox_wallet、netfox_jobs、netfox_job_status、netfox_generate、netfox_cancel。實際清單會依金鑰權限縮減。生成回傳 JSON 的 id，不會阻塞等待影片完成。
{
"taskType": "image_generation",
"inputPayload": {
"prompt": "A red fox in a sunny garden",
"aspectRatio": "1:1"
},
"requestId": "mcp-image-demo-001"
}重要：這版採手動 API Key，不是 OAuth 登入服務。僅接受 OAuth 的遠端連接器目前不能直接使用，不能把網站密碼當 API Key。工具會提示扣點；請在 AI 客戶端保留執行確認。素材上傳與二進位下載走上述 REST API。
僅支援 stdio 的客戶端可下載 stdio 橋接套件，解壓後在 package 資料夾執行 npm ci，再用 node /絕對路徑/package/index.js 啟動，環境變數設定 NETFOX_API_KEY。需 Node.js 22+；此套件尚未發布 npm registry。