REST API 与 MCP 工作流

REST API 和 MCP 服务器运行的任务与 VlogMe 应用完全相同——Director、Video、Image 和 Audio Studio、Aisma、DUB 以及 新闻视频——使用同一个账户、同一个积分余额和同一个 Lab。

访问权限：所有已注册的 VlogMe 账户都可以使用 API 和 MCP。在 Account → API & MCP 中创建密钥即可，无需客服批准。如需大批量使用或为团队做集成，请联系 sales@vlogme.ai。

集成分为五步：

1. 在 Account → API & MCP 中创建 API 密钥（账户后台目前仅提供英文界面）。
2. 上传任务所需的照片、视频或音频，或直接使用 Lab 中的文件。
3. 获取报价：VlogMe 返回任务的准确积分价格。
4. 按该报价启动任务。任务不会以其他价格运行。
5. 通过轮询或 Webhook 跟踪任务；结果会保存到 Lab。

智能体可以通过 MCP 服务器完成同样的事：其工具涵盖任务、Director、Lab 文件、项目、模板、声音、新闻视频 和社交发布，使用与 REST 相同的密钥、余额和检查。

API 与 MCP 的变更会在开发日志中公布。

AI 智能体通过 MCP 服务器 https://vlogme.ai/mcp 使用同一个账户、密钥、余额和价格。每个客户端的具体步骤见 MCP 服务器设置：

• Claude Code、Cursor 和 VS Code
• Gemini CLI 和 Codex
• n8n 工作流

在 Claude Code 中只需一条命令，密钥放在 VLOGME_API_KEY 中：

claude mcp add --transport http vlogme https://vlogme.ai/mcp --header "Authorization: Bearer $VLOGME_API_KEY"

在任何付费任务之前，智能体都会先获取报价并向您展示积分。下方的 MCP 服务器 章节列出了所有工具及其所需的密钥权限。

每个请求都在 Authorization 请求头中携带密钥：

Authorization: Bearer vma_…

• 密钥能做的，就是您在 Account → API & MCP 中创建它时勾选的内容：
  • read：列出 Lab 文件、任务和余额，并获取报价。每个密钥都有此权限。
  • write：上传和导入文件、重命名和归档文件、保存项目、在 Director 中规划和准备素材，并按报价启动付费任务。
  • delete：删除文件、项目、克隆声音和新闻监控。删除无法撤销。
  • share：创建和撤销公开分享链接。
  • publish：在已连接的社交账号上发布或定时发布视频。
• 在有这些选项之前创建的密钥保留原有权限：“Read”密钥只读；“Read and create jobs”密钥与以前一样，还可以删除和分享。
• 密钥无权发起的请求会以 403 和 code: scope_missing 被拒绝。GET /api/me 会显示该密钥自身的 token.scopes。
• 密钥的有效期为 1 至 365 天（默认 90 天）。您可以随时在 Account → API & MCP 中撤销密钥，使用它的集成会立即停止。
• 密钥不能更改套餐、创建其他密钥、删除账户或使用管理工具；这些操作需要登录后的会话（code: session_required）。

请妥善保管密钥：密钥以您账户的权限运行，并消耗该账户的积分（服务条款）。

两个公开地址描述了集成可以发送的全部内容，无需密钥。

• GET /api/catalog 列出每一种任务 kind（按 workflow 或模型）：以 JSON Schema 描述的输入、所需的 Lab 文件、可选的时长、宽高比和清晰度、计价规则、一个示例输入及其积分价格，以及当前是否可用。?kind=video 可缩小范围。其中还包括 Director 的模式：新建项目、编辑命令、聊天发言和素材准备。
• GET /api/openapi.json 是 REST API 的 OpenAPI 3.1 描述。每个操作的 x-scope 注明所需的密钥权限。

条目中列在 server_fills 下的字段（例如视频时长）由 VlogMe 根据您的文件测量，可以不传。

任务是一项工作：一个片段、一个数字人、一张图像、一条语音轨、一次编辑、一次配音、一次 Aisma 修改、一条 新闻视频 视频或一次 Director 渲染。其 kind 为 video, avatar, image, audio, video_edit, dub, trend, aisma, voice_clone, director 之一，input 中的设置与应用中对应界面相同。

普通 Image Editor 修改在浏览器中导出，不属于服务器任务。AI 图像生成和编辑请使用 kind: image 及对应的 workflow。

例如，先为一张图像获取报价，再启动任务：

curl https://vlogme.ai/api/jobs/quote \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "image", "input": {…}}'

curl https://vlogme.ai/api/jobs \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-7d4a-4f0e-9b1a-2c3d4e5f6a7b" \
  -d '{"kind": "image", "input": {…}, "quoted_credits": 12, "quote_fingerprint": "…"}'

如果报价之后价格或输入发生变化，启动请求会以 409 被拒绝，且不会扣费：请重新获取报价。任务失败时，可退还的积分会自动退回您的余额。任务一旦启动就无法取消，因为服务商并不总能停止它。

修改 Aisma 编辑中的一个片段。已完成的 Aisma 编辑可以只重新生成其中一个片段，不必重做整个视频。GET /api/jobs/{id}/clips（id 为该编辑自身的任务）返回它的各个片段，包括序号 index 和重新生成所需的 credits。请为 input 为 {"clip": {"job_id": "<该编辑的任务 ID>", "op": "regenerate", "part": <index>, "clarification": "…"}} 的 aisma 任务获取报价并启动：补充说明 clarification 可选，片段会按该编辑原有的版本和画质生成。只收取这一个片段的积分；如果 Aisma 没有采用补充说明、无法生成该片段，或让它保持原样，则不会扣费。任务结束后，input.clip_result 中有结果 outcome，补充说明未被采用时还有原因 reason；任务的成果是更新后的完整视频，即 Lab 中的一个新文件。没有可读取片段的编辑，其 clips 为 null：它创建于片段可修改之前，或其文件已随源视频一并删除。其他情况下，disabled 说明当前为何无法修改任何片段（starting、failed、busy 或 materials；可以修改时为 null），finish 说明如何让完整视频保持最新（assemble：启动 {"clip": {"job_id": "…", "op": "assemble"}} 任务；reassemble：调用 POST /api/jobs/{id}/reassemble；null：已是最新）。mode 为 change 的片段是 Aisma 保持原样的片段：用密钥重新生成时必须提供补充说明。未扣费结束的更新每小时有次数上限：每个编辑有一个上限，账户下所有编辑合计还有一个上限；超过其中任何一个后，报价和启动任务都会返回 429 并附带 retry_after_s。Aisma 只在应用内提出澄清问题：用密钥启动的编辑不会被提问。

拥有 write 权限的密钥可以把一个想法一直做成最终的视频文件：

1. 向 POST /api/director/projects 发送 {"version": 2, "concept": "…"} 创建项目。
2. 带上新的 client_request_id 和项目的 base_revision 调用 POST /api/director/projects/{id}/turns，请 Director 规划。GET /api/director/turns/{发言 id}?wait=30 会等到规划完成或 Director 提出问题；用 POST /api/director/turns/{发言 id}/answer 回答。
3. POST /api/director/projects/{id}/prepare 免费准备图片、声音和音乐，GET /api/director/projects/{id}/view 显示准备情况。准备需要一些时间：请重新读取 /view，直到所有 materials 都变为 ready。
4. POST /api/director/projects/{id}/render/quote 为视频报价（remake_scene_numbers 可重新制作选定的场景），再带上该 revision、quoted_credits、quote_fingerprint 和 Idempotency-Key 调用 POST /api/director/projects/{id}/render 启动。如果报价之后规划有变，启动会以 409（code: revision_conflict）被拒绝，且不会扣费。
5. 用 GET /api/jobs/{任务 id}?wait=30 等到任务结束；然后 GET /api/director/projects/{id}/result 返回视频和字幕，链接有效期为 15 分钟。

通过密钥进行的规划、聊天和免费准备，与应用共用您账户的同一份免费额度：大量规划的代理也会用掉应用的额度。额度暂时用完时，响应中会带有 limited: true。

人物和地点图片在额度内免费。超出后，免费账户的图片不会生成：/prepare 响应会把它们列在 plan_required（以及 skipped）中，需要订阅套餐才能继续生成图片。有套餐时，超出其额度的图片会连同价格列在 charged 中：用 POST /api/jobs/quote（kind director，input {"v": 2, "stage": "materials", "project_id": "…", "revision": 3, "keys": ["…"]}）报价，然后像其他付费任务一样启动。渲染视频时在 /view 中仍为 missing 的图片会在渲染中生成，并包含在其报价中。为已完成的图片重新生成一版（再试一次）时，调用 POST /api/director/projects/{id}/prepare，在 keys 中放入该图片的键，并加上 "regenerate": true。

要修改规划，可以向 /turns 发送消息（加上 scope.block_ids 只修改部分场景），或向 POST /api/director/projects/{id}/edits 发送遵循 GET /api/catalog 中 director.edit_command_schema 的结构化编辑。POST /api/director/projects/{id}/undo 恢复较早的版本。每次修改都带上您读取到的 base_revision 和新的 client_request_id：过时的版本会以 409 被拒绝，重复的 client_request_id 会重放该修改，而不会执行两次。

添加到规划中的文件需要 rights_confirmed: true。通过密钥发送时，这表示您本人确认拥有使用这些文件及其中人物的权利（服务条款）。

• GET /api/assets 列出您的 Lab 文件，最新的在前。section=main 为文件（成片、结果和上传），working 为项目制作中使用的文件，archived 为归档，all（默认）为所有未归档的文件。可按 kind、project_id（或 none）和 q 筛选；fields=compact 不返回元数据；用 limit 和返回的 next_offset 翻页。GET /api/assets/working-projects 按项目汇总工作文件。
• 使用 mime_type、bytes 和 title 调用 POST /api/assets/intent 可在 Lab 中预留文件，并返回可续传（tus）上传地址和令牌。图像：JPEG、PNG、WebP、BMP。视频：MP4、MOV、M4V，最长 150 分钟。音频：MP3、M4A、WAV、OGG。每个文件最大 1 GB。
• 附带 content_sha256（文件的 SHA-256，64 个小写十六进制字符）时，您已上传过的相同文件会被直接复用：返回 200，包含 reused: true 和该文件，无需再上传。如需保留第二份副本，请同时发送 allow_duplicate: true。
• POST /api/assets/{id}/complete 会检查上传，之后即可在任务的 input 中使用该文件。
• 使用 API 密钥时，intent 的响应还包含 put_url：一个签名地址，可用一次 PUT 上传整个文件（curl -T clip.mp4 -H "Content-Type: video/mp4" "$put_url"），无需 tus。Idempotency-Key 请求头（UUID）让重试返回同一个文件。
• 带上 {"url": "https://…"} 和 Idempotency-Key 调用 POST /api/assets/import，会在后台从公开 HTTPS 地址导入文件。响应为包含新文件 id 的 202；之后 GET /api/assets/{id} 显示 import.status，直到文件就绪，或显示带 error_code 的 failed。VlogMe 自身的地址、私有网络和 IP 地址会被拒绝。
• PATCH /api/assets/{id} 带 title 可重命名文件，带 archived: true 可将其移入归档（false 恢复）；项目制作中使用的文件保留在工作文件中。
• DELETE /api/assets/{id} 永久删除文件（delete 权限）。正在运行的任务仍需要的文件会以 409 被拒绝。
• GET /api/assets/working-projects/{id}/cleanup 显示清理会在某个项目中删除哪些文件（较早的版本、未使用的图片、残留文件），并注明每个文件的原因。向同一地址 POST 该预览中的 asset_ids，每次请求最多删除五个（delete 权限）。任何文件都不会被自动删除。
• GET /api/assets/{id}/download 返回有效期 60 秒的私密链接；ttl 最长可延至一小时，redirect=1 会以重定向到文件的方式响应，因此 curl -L 即可下载。

通过 API 上传的文件与在应用中上传的文件一样，会私密保存在您的 Lab 中。

• GET /api/projects 列出您的项目，最新的在前：Director 项目（附想法和摘要），以及 新闻视频、Aisma、DUB 和 Image Editor 草稿（附已保存的数据）。可按 kind 筛选；用 limit 和返回的 next_cursor 翻页。
• 带 kind、title 和 data 调用 POST /api/projects 保存新草稿；Idempotency-Key 请求头让重试返回同一份草稿。带上草稿当前的 revision 调用 PUT /api/projects/{id} 保存修改，过时的版本会以 409 被拒绝。DELETE /api/projects/{id} 删除项目（delete 权限）；其 Lab 文件会保留。
• Director 项目通过 POST /api/director/projects（见上文）创建，而不是作为草稿。
• GET /api/templates 列出已发布的 Aisma 模板（category、q、limit、cursor），GET /api/templates/{id} 显示单个模板，带 Idempotency-Key 调用 POST /api/templates/{id}/open 可将其作为新项目打开。
• GET /api/voices 列出任务和 Director 角色可用的声音：预设声音和您已就绪的克隆声音。GET /api/voice-clones 列出您的克隆声音及其状态，DELETE /api/voice-clones/{id} 删除克隆声音，包括在声音服务商处的副本（delete 权限）。

• GET /api/trends/search?q=… 搜索近期新闻（language 为 en 或 ru；country、category、domains、sort_by）。POST /api/trends/script 依据新闻来源撰写脚本，POST /api/trends/verify 将脚本与这些来源进行核对。
• 新闻监控按计划查找新报道：GET 和 POST /api/trends/monitors，PUT 和 DELETE /api/trends/monitors/{id}。
• GET /api/social/connections 显示已连接的社交账号，GET /api/social/publications 显示您的发布及其状态。连接账号需要在应用中登录。
• 带 asset_id（已就绪的视频）和 platform，可选 caption、headline、visibility、cover_asset_id 和 scheduled_at，以及 Idempotency-Key 调用 POST /api/social/publications，即可发布或定时发布视频。这需要 publish 权限，只有您在创建密钥时勾选了它，密钥才具有此权限。发布内容对所有人可见：代理应向您展示视频、平台和文案，并在您明确同意后才发布。
• POST /api/social/publications/{id}/cancel 取消尚未发出的发布（publish 或 write 权限）。
• 视频编辑器预览（POST /api/video-editor/preview）返回 MP4 流，因此只能通过 REST 使用。

有两种方式可以得知工作何时完成。

长轮询。GET /api/jobs/{id}?wait=30 和 GET /api/director/turns/{id}?wait=30 会在指定秒数（0 至 30）内等待任务或发言结束（Director 提出问题时，发言也会停止），然后连同 waited_seconds 一起返回。仍在进行时，retry_after_s 提示何时再次查询。无法接收 Webhook 的笔记本电脑上的代理就以这种方式等待。

Webhook。使用 API 密钥启动任务时添加 webhook_url（一个公开的 HTTPS 地址），任务结束时 VlogMe 会发送事件：

{"id": "job.<job id>.succeeded", "type": "job.succeeded", "created_at": "…",
 "job": {"id": "…", "kind": "image", "status": "succeeded", "result_asset_id": "…", "error_code": null}}

• 事件类型为 job.succeeded、job.failed 或 job.partial（部分成果已在 Lab 中，缺失部分的积分已退回）。审核中的任务（needs_review）尚未结束，结束时才会发送事件。
• 最终合成失败的部分完成任务，可通过 POST /api/jobs/{id}/reassemble 免费重新合成。合成结束后，会有新事件告知结果；即使再次合成失败、任务仍为部分完成，也会发送事件。每种结果都有各自的事件 ID（部分完成的事件 ID 以其 error_code 结尾：job.<job id>.partial.<error code>；免费重新合成失败 n 次后，还会加上 .retry<n>）。该次数可在 GET /api/jobs/{id} 的 reassembly_failures 中查看。片段被修改过的 Aisma 编辑要用另一种方式合成：对它发出这个请求会以 409（clip_job_required）被拒绝，视频改由 input 为 {"clip": {"job_id": "<该编辑的任务 ID>", "op": "assemble"}} 的任务免费合成。片段任务以 aisma_clip_video_pending 部分完成时，也用同样的任务合成视频。
• 每次发送都带有 X-VlogMe-Event-Id、X-VlogMe-Timestamp 和 X-VlogMe-Signature: v1=<hex>：以您 API 密钥的 SHA-256 摘要为密钥，对 <timestamp>.<body> 计算的 HMAC-SHA256。请校验签名，并拒绝过旧的时间戳。
• 未收到 2xx 响应的发送最多重试八次，间隔从 30 秒逐步延长到每小时一次。撤销密钥后发送即停止。

支持 Model Context Protocol 的 AI 智能体使用同一个 Authorization: Bearer 密钥连接 https://vlogme.ai/mcp（基于 HTTP POST 的 JSON-RPC 2.0）；https://vlogme.ai/api/mcp 是同一服务器的另一个地址。支持的协议版本：2026-07-28（无状态，使用 Mcp-Method 和 Mcp-Name 请求头以及 server/discover），以及 2025-11-25、2025-06-18 和 2025-03-26（带 initialize，并以客户端请求的版本应答）。没有 MCP-Protocol-Version 请求头的请求按 2025-03-26 处理。单个请求最大 1 MB。

这些工具涵盖密钥通过 REST 能做的事。每个工具需要表中列出的权限。工具列表与密钥权限无关；密钥无权发起的调用会以 code: scope_missing 的拒绝结果返回。在 URL 后加上 ?tools=all（https://vlogme.ai/mcp?tools=all），列表就会列出表中的所有工具；各客户端的连接方法见 MCP 服务器设置。

• 只读工具带有 readOnlyHint。执行删除的工具带有 destructiveHint，其描述以“Irreversible.”开头；让内容公开的工具，描述以“Public.”开头；付费工具会注明需要消耗积分。代理必须先向您确认这些调用。
• 参数会按每个工具的模式进行检查。错误或未知的参数会在发送任何请求之前被拒绝，返回带 isError: true 和 code: invalid_input 的结果。
• 每个列表工具都接受 limit（1 至 50，默认 20）和 cursor，并返回 next_cursor（最后一页为 null）。
• vlogme_wait_job 和 vlogme_director_turn 每次调用最多等待 30 秒；只要响应中有 retry_after_s，就请再次调用。
• 资源：resources/read 提供 vlogme://docs/agents（面向代理的指南：从想法到视频、计费规则、等待与错误）、vlogme://catalog（任务目录）和 vlogme://openapi（OpenAPI 描述）。initialize 会返回概述同样流程的简短说明。

通过 MCP 启动任务：

1. 使用 kind 和 input 调用 vlogme_quote_job，并确认返回的 credits。
2. 使用相同的 kind 和 input、新的 UUID idempotency_key、设为返回值 credits 的 quoted_credits，以及未修改的 quote_fingerprint 调用 vlogme_create_job。Aisma 还需要原样传入报价中的 quote_proof。
3. 如果确认已过期，或价格、输入发生变化，请重新获取并确认报价后再试。已接受的请求使用相同的 idempotency_key 重试会返回同一个任务。

Director 视频遵循同样的规则：先调用 vlogme_director_quote_render，向用户展示价格，再带上该报价和 idempotency_key 调用 vlogme_director_render。

可选的 webhook_url 用于接收上述任务事件。MCP 与 REST 使用相同的 API 密钥、积分余额和价格检查。

在 Codex 中，将服务器添加到 ~/.codex/config.toml，并把密钥保存在环境变量 VLOGME_API_KEY 中：

[mcp_servers.vlogme]
url = "https://vlogme.ai/mcp"
bearer_token_env_var = "VLOGME_API_KEY"
tool_timeout_sec = 120

• 任务消耗的积分与应用中相同，从同一余额扣除；报价即价格。
• Idempotency-Key 为 UUID。将同一个键用于不同请求会被拒绝。
• Aisma 任务需要报价返回的 quote_proof。它有有效期，过期后请重新获取报价。
• Aisma 任务可带可选字段 engine：v1 或 v2，不传时为 v2。两个版本的价格和可用参考照片数量不同，各自的上限见 GET /api/catalog?kind=aisma。报价只对应一个版本：要用另一个版本开始，请重新获取报价。由模板打开的项目始终使用 v2。
• 错误以 JSON {"error": "…", "code": "…"} 返回，并附 HTTP 状态码：400 输入无效（invalid_input），403 密钥权限不允许的请求（scope_missing、session_required），404 未找到，409 价格、输入或规划已变化，429 请求过多，503 服务或服务商暂时不可用。
• 请求有频率限制。超过限制时返回 429、code: rate_limited 和 Retry-After 请求头：等待相应秒数后再试。
• 通过 MCP，被拒绝的工具调用不是 HTTP 错误：它作为带 isError: true 的工具结果返回，内容是相同的 JSON（error、status，如有还包括 code）。在 MCP 中，只有缺少或无效的密钥（401）、没有 API 访问权限的账户或外部 Origin（403）以及格式错误的请求才是 HTTP 错误。
• 通过 API 创建的内容与在应用中创建的内容一样，遵守服务条款。