快速開始
免費申請測試金鑰,用 curl 送出第一個請求,弄清楚測試金鑰能做什麼、不能做什麼,再切換到正式金鑰。
這一頁帶你從頭開始:註冊應用程式,拿到一把免費的測試金鑰,再用 curl 建立專案、在時間軸上加一段標題並算繪。任何方案都能建立測試金鑰(包括免費的 Hobby),不會扣點數,也不會真的排入算繪佇列,所以你可以先把整套整合跑通,再決定要不要付費。
註冊應用程式並建立測試金鑰
- 開啟 developer.vidmoat.com 並登入。從中國大陸登入可能需要 VPN,詳見網路說明。
- 在「應用程式(Apps)」頁面按「註冊應用程式(Register an app)」。填寫應用程式名稱(App name)、你平常會看的聯絡信箱(Contact email),用一句話說明你在做什麼(What does it do?),勾選同意開發者協議後送出。註冊應用程式是免費的。
- 開啟剛註冊的應用程式,在「API keys」區塊按「建立金鑰(Create key)」。
- 名稱(Name)寫清楚用途,例如「本機開發」;環境(Environment)維持預設的 Test;權限選 Build & render 預設組合,它在唯讀權限之外還包含
projects.write、media.write和render.write。 - 按「Create test key」。金鑰只會顯示這一次:我們只保存它的 SHA-256 雜湊值,之後誰都看不到原文。請立刻複製,或按「Download .env file」下載。弄丟了就撤銷(Revoke)再建一把。
測試金鑰不必等應用程式審核,建立後馬上就能用。
儲存金鑰並驗證
回傳結果裡的
credential.environment應該是test,credential.scopes列出這把金鑰擁有的權限。測試金鑰以
vmk_test_開頭,正式金鑰以vmk_live_開頭。前綴只是方便人在記錄檔裡一眼認出;金鑰屬於測試還是正式,由建立時的選擇決定,與文字無關。所有請求都只接受Authorization: Bearer <金鑰>這一種寫法,不支援把金鑰放在查詢參數裡。第一個請求:建立專案並算繪
依序執行下面四個指令。把
PROJECT_ID換成第一步回傳的project.id,把RENDER_ID換成第三步回傳的render.id。使用測試金鑰時,算繪會立刻變成
COMPLETED,附上test: true和一支範例影片的url:沒有真的排入佇列,也不占用匯出額度。專案和標題卻是真實的,在 Vidmoat 編輯器裡打得開。含輪詢與錯誤處理的完整腳本(curl、Node、Python 三種版本)請看英文版 Quickstart。
測試金鑰能做什麼、不能做什麼#
| 範圍 | 使用測試金鑰時 |
|---|---|
| 專案、指令、工作區 | 真實。 專案會在你的帳號上建立、編輯和刪除。 |
| 上傳和匯入 | 真實。 檔案會被保存,並計入你的儲存空間。 |
| 預覽 | 真實。 回傳的影格就是你時間軸上的實際畫面。 |
| 算繪 | 範例。 先檢查專案,然後立刻回傳一個已完成的範例檔案(test: true)。不排入佇列,不占用匯出額度。 |
| 生成(圖片、語音、貼圖、影片、轉錄) | 範例。 回傳固定的範例檔案或逐字稿,不呼叫任何模型服務,不扣點數。quoteOnly 會被忽略。 |
| Otto(剪輯 AI 代理) | 範例。 需要一個真實專案,然後回傳空的計畫,不呼叫模型。 |
| 外掛程式 | 不呼叫。 回傳 { "ok": true, "test": true }。 |
| Speech Lab 的私人聲音和推論 | 拒絕。 回傳 501,需要正式金鑰。 |
| Telegram 機器人使用者 | 可以讀取;修改會被拒絕,因為那是正式機器人上的真實使用者。 |
範例檔案放在 API 網域的 /fixtures/v1/ 底下,回應帶有 Access-Control-Allow-Origin: *,瀏覽器裡的測試頁面也能直接載入。完整說明請看英文版 Test and live keys。
切換到正式金鑰#
正式金鑰(vmk_live_)需要同時符合三項條件:已同意開發者協議(註冊應用程式時已完成)、應用程式通過審核、方案包含正式 API 權限(Studio、Team 或 Enterprise)。內容清楚的申請通常在註冊時就自動通過,審核狀態會顯示在應用程式的「API keys」頁面上。
- 在同一個應用程式裡再建立一把金鑰,環境(Environment)選 Live。
- 替換環境變數裡的金鑰,程式碼不用改。正式金鑰的回應結構相同,只是沒有
test和note欄位;算繪回應會多一個applied物件,說明方案對這次算繪做了什麼決定。 - 上線前,改用 Webhook 的
render.completed事件取代輪詢,並讀一遍錯誤與重試。送出算繪的請求逾時後不要直接重送,先查詢既有的算繪,避免重複排入佇列。
正式金鑰會扣真實點數。金鑰只放在你的伺服器上,不要寫進瀏覽器或 App 的程式碼裡。權限是必要條件但不是充分條件:方案和點數餘額仍然適用,例如方案不含影片生成時,即使金鑰有 ai.video 權限也會回傳 402 plan_required。