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(剪辑智能体)示例。 需要一个真实项目,然后返回空的计划,不调用模型。
插件不调用。 返回 { "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。