快速开始
免费申请测试密钥,用 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(剪辑智能体) | 示例。 需要一个真实项目,然后返回空的计划,不调用模型。 |
| 插件 | 不调用。 返回 { "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。