# 快速開始

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

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

> **說明：主控台目前是英文介面。** 下文先用中文說明，再在括號裡註明介面上的英文原文，例如「建立金鑰（Create key）」，方便你對照操作。

### 第 1 步：註冊應用程式並建立測試金鑰

1. 開啟 [developer.vidmoat.com](https://developer.vidmoat.com/developer/apps) 並登入。從中國大陸登入可能需要 VPN，詳見[網路說明](https://developer.vidmoat.com/developer/docs/zh-tw/network#sign-in)。
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 步：儲存金鑰並驗證

```bash macOS / Linux
export VIDMOAT_KEY="vmk_test_你的金鑰"

curl https://api.vidmoat.com/v1/me \
  -H "Authorization: Bearer $VIDMOAT_KEY"
```

```text Windows PowerShell
$env:VIDMOAT_KEY = "vmk_test_你的金鑰"

curl.exe https://api.vidmoat.com/v1/me `
  -H "Authorization: Bearer $env:VIDMOAT_KEY"
```

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

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

### 第 3 步：第一個請求：建立專案並算繪

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

```bash 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 編輯器](https://www.vidmoat.com/dashboard)裡打得開。

含輪詢與錯誤處理的完整腳本（curl、Node、Python 三種版本）請看英文版 [Quickstart](https://developer.vidmoat.com/developer/docs/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](https://developer.vidmoat.com/developer/docs/concepts/test-and-live-keys)。

> **注意：請用專門的測試專案。** 測試金鑰做的編輯是真實的。如果把測試金鑰指向正式專案，那個專案就會被改動。請另外建一個測試專案，用完刪除。

> **注意：透過 MCP 使用時不一樣。** MCP 伺服器不會把結果換成範例。用測試金鑰連線 MCP 時，工具會以你的帳號身分真實執行：生成類工具依標價扣點數，匯出占用匯出額度。只想零成本試接，請先用上面的 REST 呼叫。詳見 [MCP 頁面](https://developer.vidmoat.com/developer/docs/zh-tw/mcp#test-keys-over-mcp)。

## 切換到正式金鑰

正式金鑰（`vmk_live_`）需要同時符合三項條件：已同意開發者協議（註冊應用程式時已完成）、應用程式通過審核、方案包含正式 API 權限（Studio、Team 或 Enterprise）。內容清楚的申請通常在註冊時就自動通過，審核狀態會顯示在應用程式的「API keys」頁面上。

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

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

- [連線 MCP 伺服器](https://developer.vidmoat.com/developer/docs/zh-tw/mcp)：在 Cherry Studio、Trae、Qwen Code、Kimi Code CLI 和 Cursor 中接入。
- [網路說明](https://developer.vidmoat.com/developer/docs/zh-tw/network)：從中國大陸、香港、台灣等地連線與登入時需要知道的事。
- [Authentication（英文）](https://developer.vidmoat.com/developer/docs/authentication)：API 金鑰和 OAuth 的完整說明。
- [Scopes（英文）](https://developer.vidmoat.com/developer/docs/scopes)：每項權限能做什麼。

---

來源：https://developer.vidmoat.com/developer/docs/zh-tw/quickstart
上一頁：[网络与访问说明](https://developer.vidmoat.com/developer/docs/zh-cn/network.md)
下一頁：[連線 MCP 伺服器](https://developer.vidmoat.com/developer/docs/zh-tw/mcp.md)
全部文件：https://developer.vidmoat.com/llms-full.txt
