# 快速开始

> 免费申请测试密钥，用 curl 发出第一个请求，弄清测试密钥能做什么、不能做什么，再切换到正式密钥。

本页带你从零开始：注册应用，拿到一把**免费的测试密钥**，再用 curl 创建项目、在时间线上加一段标题并渲染。测试密钥在任何套餐上都能创建（包括免费的 Hobby），不消耗积分，也不会真正排队渲染，所以你可以先把整套集成跑通，再决定要不要付费。

> **说明：控制台目前是英文界面。** 下文先用中文说明，再在括号里注明界面上的英文原文，例如「创建密钥（Create key）」，方便你对照着点。

### 第 1 步：注册应用并创建测试密钥

1. 打开 [developer.vidmoat.com](https://developer.vidmoat.com/developer/apps) 并登录。在中国大陆登录可能需要 VPN，详见[网络说明](https://developer.vidmoat.com/developer/docs/zh-cn/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（剪辑智能体） | **示例。** 需要一个真实项目，然后返回空的计划，不调用模型。 |
| 插件 | **不调用。** 返回 `{ "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-cn/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-cn/mcp)：在 Cherry Studio、Trae、Qwen Code、Kimi Code CLI 和 Cursor 中接入。
- [网络说明](https://developer.vidmoat.com/developer/docs/zh-cn/network)：在中国大陆访问 API、文档和登录时需要知道的事。
- [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-cn/quickstart
上一页：[Changelog](https://developer.vidmoat.com/developer/docs/changelog.md)
下一页：[连接 MCP 服务器](https://developer.vidmoat.com/developer/docs/zh-cn/mcp.md)
全部文档：https://developer.vidmoat.com/llms-full.txt
