Skip to content

快速開始

免費申請測試金鑰,用 curl 送出第一個請求,弄清楚測試金鑰能做什麼、不能做什麼,再切換到正式金鑰。

這一頁帶你從頭開始:註冊應用程式,拿到一把免費的測試金鑰,再用 curl 建立專案、在時間軸上加一段標題並算繪。任何方案都能建立測試金鑰(包括免費的 Hobby),不會扣點數,也不會真的排入算繪佇列,所以你可以先把整套整合跑通,再決定要不要付費。

  1. 註冊應用程式並建立測試金鑰

    1. 開啟 developer.vidmoat.com 並登入。從中國大陸登入可能需要 VPN,詳見網路說明。
    2. 在「應用程式(Apps)」頁面按「註冊應用程式(Register an app)」。填寫應用程式名稱(App name)、你平常會看的聯絡信箱(Contact email),用一句話說明你在做什麼(What does it do?),勾選同意開發者協議後送出。註冊應用程式是免費的。
    3. 開啟剛註冊的應用程式,在「API keys」區塊按「建立金鑰(Create key)」。
    4. 名稱(Name)寫清楚用途,例如「本機開發」;環境(Environment)維持預設的 Test;權限選 Build & render 預設組合,它在唯讀權限之外還包含 projects.write、media.write 和 render.write。
    5. 按「Create test key」。金鑰只會顯示這一次:我們只保存它的 SHA-256 雜湊值,之後誰都看不到原文。請立刻複製,或按「Download .env file」下載。弄丟了就撤銷(Revoke)再建一把。

    測試金鑰不必等應用程式審核,建立後馬上就能用。

  2. 儲存金鑰並驗證

    macOS / Linux
    export VIDMOAT_KEY="vmk_test_你的金鑰"
    
    curl https://api.vidmoat.com/v1/me \
      -H "Authorization: Bearer $VIDMOAT_KEY"

    回傳結果裡的 credential.environment 應該是 test,credential.scopes 列出這把金鑰擁有的權限。

    測試金鑰以 vmk_test_ 開頭,正式金鑰以 vmk_live_ 開頭。前綴只是方便人在記錄檔裡一眼認出;金鑰屬於測試還是正式,由建立時的選擇決定,與文字無關。所有請求都只接受 Authorization: Bearer <金鑰> 這一種寫法,不支援把金鑰放在查詢參數裡。

  3. 第一個請求:建立專案並算繪

    依序執行下面四個指令。把 PROJECT_ID 換成第一步回傳的 project.id,把 RENDER_ID 換成第三步回傳的 render.id。

    first-render.sh
    BASE="https://api.vidmoat.com/v1"
    
    # 1. 建立專案,記下回傳的 project.id
    curl --fail-with-body -sS -X POST "$BASE/projects" \
      -H "Authorization: Bearer $VIDMOAT_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"你好,Vidmoat"}'
    
    # 2. 在時間軸上加一段 3 秒的標題
    curl --fail-with-body -sS -X POST "$BASE/projects/PROJECT_ID/commands" \
      -H "Authorization: Bearer $VIDMOAT_KEY" \
      -H "Content-Type: application/json" \
      -d '{"commands":[{"op":"addTextClip","text":"Hello","start":0,"duration":3}]}'
    
    # 3. 算繪,記下回傳的 render.id
    curl --fail-with-body -sS -X POST "$BASE/renders" \
      -H "Authorization: Bearer $VIDMOAT_KEY" \
      -H "Content-Type: application/json" \
      -d '{"projectId":"PROJECT_ID"}'
    
    # 4. 查詢算繪結果
    curl --fail-with-body -sS "$BASE/renders/RENDER_ID" \
      -H "Authorization: Bearer $VIDMOAT_KEY"

    使用測試金鑰時,算繪會立刻變成 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」頁面上。

  1. 在同一個應用程式裡再建立一把金鑰,環境(Environment)選 Live。
  2. 替換環境變數裡的金鑰,程式碼不用改。正式金鑰的回應結構相同,只是沒有 test 和 note 欄位;算繪回應會多一個 applied 物件,說明方案對這次算繪做了什麼決定。
  3. 上線前,改用 Webhook 的 render.completed 事件取代輪詢,並讀一遍錯誤與重試。送出算繪的請求逾時後不要直接重送,先查詢既有的算繪,避免重複排入佇列。

正式金鑰會扣真實點數。金鑰只放在你的伺服器上,不要寫進瀏覽器或 App 的程式碼裡。權限是必要條件但不是充分條件:方案和點數餘額仍然適用,例如方案不含影片生成時,即使金鑰有 ai.video 權限也會回傳 402 plan_required。