Zvid

@zvid/mcp

官方 Zvid Agent 和 MCP 服务。Creator 遵循质量优先的工作流：规划需求说明，调整设计示例或库资源，验证准确的项目 JSON，保存可供审核的草稿，然后仅在获得批准后渲染。Automation 和 Developer 提供可信的直接操作。

身份验证

身份验证方式恰好有两种。以下每种设置都使用其中一种：

#	方式	适用场景	所需内容
1	OAuth — 使用 Zvid 账户登录（推荐）	托管端点 https://mcp.zvid.io/mcp	Zvid 账户，以及任意支持 OAuth 的 Streamable HTTP MCP 客户端。无需创建或粘贴 API 密钥。
2	API 密钥（zvid_…）	通过 X-Api-Key 标头访问托管端点，或用于本地 stdio / 可自托管部署	从 app.zvid.io/api-keys 获取密钥；使用 stdio 需要 Node.js ≥ 18

方式 1 — OAuth 登录。 将 https://mcp.zvid.io/mcp 添加到 MCP 客户端， 并在提示时登录。该端点会发布 OAuth 发现元数据， 使用 authorization code + PKCE 和唯一作用域 zvid:mcp，并颁发 有效期较短且会轮换的访问令牌（可根据 RFC 7009 撤销）。以下针对特定客户端的说明均采用此方式。

方式 2 — API 密钥。 在 app.zvid.io/api-keys 创建密钥，然后选择以下任一方式：

• 托管： 在 https://mcp.zvid.io/mcp 上通过 X-Api-Key 标头发送密钥 — 适用于无法运行 OAuth 流程的程序化客户端，或用于旧版访问。
• 本地 stdio / 可自托管部署： 按照本地 stdio / 可自托管设置中的说明，通过 ZVID_API_KEY / --api-key 传递密钥。 stdio 传输仅支持 API 密钥，因为 MCP OAuth 是为 HTTP 传输定义的。

托管设置（推荐）

托管端点为 https://mcp.zvid.io/mcp。它支持两种 身份验证方式：OAuth 登录（方式 1 — 以下客户端说明采用此方式） 以及在 X-Api-Key 标头中提供 API 密钥（方式 2）。

Claude Code

claude mcp add --transport http zvid https://mcp.zvid.io/mcp
claude mcp login zvid

你也可以在 Claude Code 中打开 /mcp 并在那里进行身份验证。

OpenAI Codex

注册服务，然后在 MCP 设置或命令行中进行身份验证：

codex mcp add zvid --url https://mcp.zvid.io/mcp
codex mcp login zvid

仪表板会为 MCP 客户端保存默认工具配置 和每次渲染的最高积分数。客户端可以在端点中指定 具体值来连接，例如 https://mcp.zvid.io/mcp?profile=creator&maxRenderCredits=60；这是连接 配置，模型无法在对话过程中更改。每次渲染的默认积分上限为 120；如果设置了仪表板上限，则该上限是 硬性上限：实际生效的上限取仪表板值与 端点请求值中的较低者。

下载官方 n8n 工作流时，会将仪表板中的两项默认设置复制到工作流 JSON 中。 随后，每个工作流都可以在本地选择其他具体配置和 积分上限，而无需更新仪表板或任何其他工作流。

本地 stdio / 可自托管设置

npm/stdio 入口使用 API 密钥（身份验证方式 2）。 配置的解析顺序为 CLI 标志、环境变量，然后是 ~/.zvid-mcp.json：

npx -y @zvid/mcp --api-key zvid_your_key_here --api-url http://localhost:4000

环境变量	CLI 标志	必需	默认值	用途
ZVID_API_KEY	--api-key zvid_…	仅 stdio	—	Zvid API 密钥
ZVID_API_URL	--api-url http://…	否	https://api.zvid.io	Orchestrator 基础 URL
ZVID_MCP_PROFILE	--profile creator	否	creator	工具配置
ZVID_MCP_MAX_RENDER_CREDITS	—	否	120	旧版/回退托管限额；以控制面板和显式 n8n 值为准
ZVID_MCP_MAX_BULK_ITEMS	—	否	25	自动化/开发者批量调用的项目上限
ZVID_MCP_QUOTE_SECRET	—	托管环境	进程随机生成	多实例报价共用的 HMAC 密钥

对于可自托管的 OAuth 部署，请确保两个服务上的资源和颁发者完全一致：

服务	变量	生产环境默认值
Orchestrator	OAUTH_ISSUER	https://api.zvid.io
Orchestrator	OAUTH_MCP_RESOURCE	https://mcp.zvid.io/mcp
Orchestrator	OAUTH_CONSENT_URL	https://app.zvid.io/oauth/authorize
MCP	ZVID_MCP_RESOURCE	https://mcp.zvid.io/mcp
MCP	ZVID_OAUTH_ISSUER	https://api.zvid.io

Orchestrator 还接受 OAUTH_ACCESS_TOKEN_TTL_SECONDS 和 OAUTH_REFRESH_TOKEN_TTL_SECONDS；默认值分别为 1 小时和 30 天。

在代码检出目录中运行：

cd mcp && npm install && npm run build
claude mcp add zvid --env ZVID_API_KEY=zvid_your_key_here -- node /absolute/path/to/mcp/dist/index.js

默认 Creator 工作流

默认的 creator 配置是原先的高级创作界面。它提供规划、设计示例、创意库搜索、素材、架构/文档、修复、验证、项目和模板，以及支持审批的草稿工具。

Creator 会有意拒绝缺少完整项目 payload 的 create_media 和 revise_media 调用。这可防止能力较弱的模型根据简介随意生成质量不佳的布局。Agent 必须规划、调整或组装精确的 payload，在远程端进行验证，修复所有错误和布局警告，然后才能保存草稿。create_media 不会消耗额度；render_media 仍需要用户批准的签名报价。

当用户要求可重复使用的模板，而非一次性视频或图片时，create_media_template 会将参数化项目——一个通过 {{name}} 占位符引用安全默认值的顶层 variables 对象——保存为持久化的 tpl_… 模板。它会返回已声明的变量、渲染未更改默认值的额度估算，以及编辑器深层链接 （https://editor.zvid.io/?template=<id>）。随后，create_media_from_template 会用新的变量值实例化该模板，生成带有签名报价、需审批的草稿。两个调用都不会消耗额度。在 creator 配置中，create_media_template 需要完整的参数化 payload，与 create_media 的要求一致。

渲染与起草刻意分开。报价令牌经过 HMAC 签名，有效期为 15 分钟，并绑定草稿 ID、项目版本、规范化 payload 哈希、媒体类型和预估额度；提交前会立即重新验证。幂等 UUID 可防止重试导致重复操作。

功能配置

配置	适用场景	功能
readonly	检查	get_media、list_media、get_account
creator	大多数用户	高质量创作、素材库、验证、项目/模板及经批准的渲染
automation	可信工作流	Creator 工具，以及直接渲染、设有上限的批量渲染和 webhook 操作
developer	完整 API 开发	所有已注册的非破坏性/原始工具

所有配置中都禁用了更新和删除工具。存储的 webhook 密钥会由 get_webhook 脱敏；只有 create_webhook 会返回新密钥。MCP 批量调用通常最多允许 25 个项目，具体受账户限制约束。直接 REST API 的 500 项硬上限不会提高此工具上限；请将工作拆分为适当大小的批次。

该服务还提供四个由用户调用的工作流提示词（产品宣传、社交短视频、缩略图和方形帖子），以及安全的 MCP 资源 zvid://authoring/guidelines 和 zvid://account/summary。

Creator、Automation 和 Developer 工具

以下低级功能仅在上述配置中可用：

工具	描述
plan_creative_video	根据简报规划分镜和艺术指导，并提供 libraryCandidates：根据与简报的匹配度为已发布示例排序，并决定采用改编还是组合。支持 consistent、fresh 和 explore 模式、排除近期素材、品牌令牌、风格包和场景配方
find_matching_examples	根据简报为整个已发布示例库排序（类别同义词、宽高比／时长匹配），并返回带缩略图的候选项及决策：adapt-example、adapt-or-assemble 或 assemble-similar（含设计模板／画布预设／形状模块）
start_from_example	获取示例的可直接渲染项目 JSON 和改编映射（变量、文本／媒体槽位、场景摘要、字体）及改编约定——高级路径：保留布局，替换文案／媒体／品牌。如果高级示例受方案限制，会推荐免费替代项
render_from_example	自动化／开发者直接渲染：通过示例 slug + 变量值保存模板、验证并排入付费渲染队列。创作者使用 create_media_from_example，然后使用经批准的 render_media
search_creative_library	搜索完整示例、动画 Design Studio 模板、画布预设或形状；已发布结果会包含预览／缩略图元数据
get_creative_asset	获取一个创意资源库条目的元数据和完整 JSON 内容
list_stock_providers / search_stock_media	查看图库素材功能，并在 Zvid 的图库中搜索可直接渲染的媒体 URL
get_project_schema	实时且适配调用者方案的项目载荷或完整渲染请求 JSON Schema（draft 2020-12），并提供验证说明、专业创作指南和必需工作流；端点不可用时回退到捆绑的默认架构
validate_project_json	渲染前验证载荷——提供字段级错误，免费。也会检查布局问题：文本重叠、预设忽略 x/y、画布外的框、内边距裁切、对比度低。remote: true 还会使用你方案的实际限制运行实时 API 验证
list_supported_elements	所有元素类型（IMAGE、VIDEO、GIF、SVG、TEXT、AUDIO、SUBTITLE、SCENE）及必填字段
get_element_docs	各元素文档：每个字段、约束、注意事项和有效示例
get_example_payload	经过验证的示例载荷：宣传视频、模板渲染、静态图像、字幕、Webhook 流程
repair_project_json	对无效载荷进行保守的自动修复，并说明每项更改
create_render	根据项目 JSON（payload）或 template + variables 将视频渲染加入队列
create_image_render	将静态图像渲染（PNG/JPEG/WebP）加入队列；支持 snapshotTime、quality、transparent
get_render	作业状态（waiting|active|completed|failed）、进度、输出 url + thumbnailUrl
list_renders	列出渲染作业（按 type 筛选）
create_bulk_render	一个模板／载荷 × N 组变量 → N 个作业（MCP 默认最多 25 个；同时受账户限制约束）
get_bulk_render / list_bulk_renders	查看批量任务
list_templates / get_template	浏览自有模板；get_template 返回完整项目 JSON
create_template / duplicate_template	创建通过方案验证的可复用模板，或创建一个可编辑的活动副本
preview_template	试运行变量解析和验证——不消耗额度
list_projects / get_project / create_project	编辑器草稿项目（在 https://editor.zvid.io/?project=<id> 打开）
list_webhooks / create_webhook / get_webhook / test_webhook / list_webhook_deliveries	用于 render.completed / render.failed 的 Webhook 端点（使用 HMAC-SHA256 签名）
get_credits / get_usage_stats	额度余额和使用情况

感知 Schema 的创作

Schema 工具使用一个共享模块（../schema，作为 src/zvidSchema.ts 随附），该模块与后端验证一同维护，并通过对等测试与后端验证保持一致。get_project_schema 优先使用当前感知调用方套餐的端点。标记为 live: false 的结果是捆绑的回退版本，并不能证明当前账户的限制。使用 validate_project_json 并设置 remote: true，在渲染前验证确切的项目。本地 Schema 无法证明远程媒体能够下载，也无法证明合成效果在视觉上正确。

服务还会将此工作流作为 MCP instructions 发布，因此符合规范的客户端会在初始化时收到它。AI 客户端创作视频的示例优先流程：

1. 使用项目简介、格式、时长、品牌和变体模式调用 plan_creative_video。响应包含排名后的 libraryCandidates 和一项决策。
2. 决策为 adapt-example 时：使用 start_from_example 检查示例，然后向 create_media_from_example 提供新的变量值，以保存可供审核的草稿并获取点数报价。除非任务需要更改，否则保留其布局和动画。支持的变量、条件和迭代在内联项目及已存储模板中均可解析；已存储模板便于复用，但并非替换变量的前提。
3. 决策为 assemble-similar（或检查后发现没有相近示例）时：使用返回的 design-templates、canvas-presets 和 shapes 模块（或 search_creative_library）组装规划好的场景方案。切勿强行套用无关的完整视频模板。
4. 使用 search_stock_media 为每个场景查找与主题相关的视觉素材和音乐 — 使用完整画质的 src URL，原始尺寸应 ≥ 画布尺寸。
5. 合成时，针对确切的形状调用 get_project_schema / list_supported_elements / get_element_docs。
6. 运行 validate_project_json（添加 remote: true，以根据调用方的真实套餐进行检查），并修复每一处错误和布局警告。仅在出现机械性错误时使用 repair_project_json。
7. 在默认的 Creator 配置文件中，使用 create_media 保存经过确切验证的负载（或使用模板／示例草稿工具）。审核草稿和报价，如有需要则进行修改，然后使用获批的报价令牌调用 render_media。使用 get_media 或 get_render 跟踪结果，直至完成。在 Automation/Developer 中，直接调用 create_render、create_image_render 和 render_from_example 会立即提交并消耗点数；它们不会创建等待审批的渲染前草稿。

对于静帧或无需完整计划的快速“制作类似 X 的内容”请求，请从 find_matching_examples 开始（静帧使用 type: "image"）。

变体行为：

• consistent 根据项目简介生成稳定种子（或接受 variationSeed），以便实现可复现的自动化。
• fresh 生成一个新的方向，并要求排除近期的素材库资源。
• explore 返回 2-5 个实质不同的风格／布局／分镜方向，而非对同一负载重新着色。

要创建可复用模板，请将最终渲染替换为 create_template。之后使用 get_template 检查模板，在渲染前使用 preview_template 进行预览，并使用 duplicate_template 创建安全的可编辑副本。更新和删除操作不会作为 MCP 工具开放。

示例提示词

• “创建一个有效的 Zvid JSON 载荷，用于制作一段包含标题和背景音乐的 10 秒宣传视频。”
• “为这款产品的发布策划三个真正不同的 9:16 创意方向，避开这些最近用过的示例 slug，然后制作最出色的一个。”
• “渲染前验证此载荷，并说明其中的问题。”
• “告诉我 TEXT 视觉素材需要哪些字段。”
• “Zvid 支持哪些字幕动画模式？”
• “此载荷失败了——修复它，并告诉我你改了什么。”
• “用模板 tpl_… 渲染一段 1080p 视频，标题为 ‘Summer Sale’，完成后把链接发给我。”
• “使用这些变量预览模板 tpl_…，并告诉我是否有任何验证失败。”
• “创建一个指向 https://example.com/hooks/zvid 的 webhook，用于接收已完成和失败的渲染事件。”
• “我还剩多少点数？本月花了多少？”

Webhook 签名验证

已注册的 webhook 投递均带有签名：X-Zvid-Signature: sha256=<hex>，其中 hex 值为 HMAC_SHA256(secret, "<X-Zvid-Timestamp>.<raw body>")。保存 create_webhook 返回的一次性密钥（whsec_…）；get_webhook 会对其进行脱敏。解析事件前，请先验证原始请求字节。

每请求的 webhookUrl 回调不带签名，也不与已注册 webhook 的密钥共用。两种回调类型都使用事件封装；精确的请求体和验证指南请参阅 webhook 文档。

开发

npm install
npm run build     # tsc → dist/
npm test          # unit + in-memory MCP round-trip tests
# real E2E against a local orchestrator:
ZVID_API_KEY=zvid_… ZVID_API_URL=http://localhost:4000 node scripts/e2e-local.mjs

发布（手动）

截至 2026 年 9 月 22 日检查时，npm 上提供 @zvid/mcp 0.1.0。托管服务与特定已安装的 npm 版本可能提供不同修订版；请查询已连接客户端的实际功能。

npm。 在 package.json 中提升 version，然后在 mcp/ 中运行 npm publish（通过 publishConfig 设置公开访问权限）。prepublishOnly 钩子会构建 dist/。

官方 MCP 注册表（registry.modelcontextprotocol.io）——将该服务列出，以便支持 MCP 的客户端发现。注册表会读取 server.json；通过在 zvid.io 上设置 DNS TXT 记录来证明对 io.zvid/* 命名空间的所有权（或者将 mcpName/server.json 中的 name 改为 io.github.Zvid-io/zvid-mcp，改用 GitHub 验证）。npm publish 后：

# one-time: install the publisher CLI, then log in (DNS or GitHub)
mcp-publisher login dns --domain zvid.io      # or: mcp-publisher login github
mcp-publisher publish                          # reads ./server.json

每次发布时都要保持版本同步——不一致会阻止发布到注册表。请同时更新以下三处：package.json 中的 version、server.json 中的 version，以及 server.json 中的 packages[0].version。两个文件中的服务名称必须一致：package.json 的 mcpName == server.json 的 name。

社区与支持

加入 Discord 上的 Zvid 社区，提问、 讨论视频自动化工作流，并分享你的创作。 如有私人账户或账单问题，请通过 https://zvid.io/contact 联系我们。