VIVID AI Studio

vivid-mcp

适用于 VIVID 的 MCP 服务——面向电商的 AI 内容工作室。将你的 VIVID 账号连接到 Claude Desktop、Claude Code、Cursor 或任何 模型上下文协议 客户端，即可在聊天中生成图片和视频、浏览图库并管理任务。

你可以做什么

工具	功能
vivid_whoami	与密钥关联的账户：套餐、额度
vivid_usage	每月用量与套餐限额
vivid_buy_credits	用户购买额度包或开启自动充值的链接——Agent 不会付款，用户在浏览器中确认
vivid_list_models	图像 / 视频 / 大模型，包含价格和功能
vivid_generate_image	文本生成图像（可选提供产品 / 人物 / 场景参考），并等待结果
vivid_generate_video	启动视频生成（Seedance 2.5、Kling O3、MiniMax H3、Gemini Omni、LTX、Grok……）
vivid_job_status	轮询任务，获取素材和下载 URL
vivid_list_jobs	最近生成的内容
vivid_list_assets · vivid_get_asset	浏览图库
vivid_download_asset	将素材保存到本地文件夹
vivid_share_asset	发布素材并获取分享链接、切换收藏状态
vivid_upload_file	上传本地文件或 URL，作为参考 / 起始帧 / 音频使用
vivid_list_references	已保存的产品（来自产品分析）和带有名称及 ID 的客户评价 / 角色——在 vivid_generate_image 的 products / testimonials 中使用名称，例如在应用中使用 #Product / @Testimonial
vivid_analyze_product · vivid_create_testimonial	从照片保存产品（免费，占用套餐额度），或根据三张照片或属性创建可重复使用的客户评价（50 个额度）——之后两者都可按名称使用
vivid_list_voices	TTS 服务提供商和预设语音，以及额度费用
vivid_chat	使用 VIVID 的大模型路由完成一次聊天——Grok、Claude、OpenAI GPT、Kimi（Wavespeed）
vivid_generate_music · vivid_music_status · vivid_list_music_providers	根据简述生成独特曲目——Suno V6（默认，两段音频共 6 个额度，器乐曲时长精确）或 MiniMax Music 3.0（14 个额度，时长仅供参考，可在编辑器中裁剪）；人声可选，生成完成后计费。渲染需要 20 秒至 3 分钟：工具最多等待 waitSec，之后返回供 vivid_music_status 使用的 taskId
vivid_analyze_audio	分析音乐 / 语音文件的节奏（BPM、节拍网格）和瞬态峰值，由服务端计算（免费）：提供动态蒙太奇的剪辑点，也由 CUT_TO_BEAT 自动使用（网格 beats | peaks）
vivid_search_sounds	在 Freesound.org 上搜索现有音乐、循环片段和音效（免费）。默认仅使用适合商业用途的许可证（CC0、CC BY），并为 CC BY 提供现成的署名文本；返回可直接放入时间线的 MP3 预览 URL
vivid_transcribe	语音转文字（Deepgram Nova-3，免费）：逐词时间戳、易读字幕，以及 SRT/VTT 导出——支持从素材、URL 或本地文件转写
vivid_retouch	编辑图像中的一个对象（文本目标、区域或蒙版），其余部分逐字节保持不变——2–6 个额度
vivid_compare_product	对比渲染结果与 SKU 照片，进行视觉质检：匹配分数、结论、差异、fixPrompt——1 个额度
vivid_product_sheet	读取已保存产品的参考表和新产品的价格（免费）
vivid_create_product_sheet	制作参考表：正面、两个角度和穿着效果，每张都与真实照片进行比对（可免费重做一次，若仍不合格则退款）——13 个额度，免费套餐用户可免费制作第一张
vivid_generate_voice	文本转语音：Gemini 3.1 Flash 预设、MiniMax Speech 2.8 HD（预设、情绪，以及账户持有人确认拥有该语音后保存在 VIVID 网页应用中的语音）、OmniVoice 语音设计、Deepgram。不会从音频文件或 URL 克隆语音
vivid_list_projects	你的项目
vivid_list_editor_projects	已保存的视频编辑器时间线
vivid_create_editor_project · vivid_get_editor_project · vivid_edit_timeline	使用与网页编辑器相同的引擎，无界面地创建和编辑视频编辑器时间线（片段、裁剪、速度、转场、16:9↔9:16、文本、蒙版、关键帧）——参见 时间线编辑
vivid_render_project · vivid_render_status	将编辑器项目加入 MP4 渲染队列并轮询状态（参见下文 渲染）
vivid_record_ui	使用本地 Chromium 对 vividai.tv（或任何网站）进行脚本化操作演示的屏幕录制，包含光标、平滑移动和点击波纹，并将录制内容上传为视频素材（参见下文 UI 录制）

设置

1. 获取 API 密钥：登录 vividai.tv → Settings → API key。
2. 连接客户端。有三种方式，任选一种：

	方式	需要 Node？	仅限本地的工具（vivid_download_asset、vivid_record_ui、本地路径）
远程	https://mcp.vividai.tv/mcp + Authorization: Bearer vk_…	否	否
连接器（Claude.ai）	https://mcp.vividai.tv/mcp，使用 OAuth — 无需粘贴密钥	否	否
连接器（ChatGPT）	https://mcp.vividai.tv/chatgpt，使用 OAuth — 无需粘贴密钥	否	否
Claude Code 插件	/plugin install vivid@vivid — OAuth，另含 VIVID 技能	否	否
Claude Desktop 扩展	下载 vivid-mcp.mcpb，双击并粘贴密钥	否（附带运行时）	是
本地（npx）	设置 VIVID_API_KEY 后运行 npx -y vivid-mcp	Node.js 20+	是
命令行	设置 VIVID_API_KEY 后运行 npx -y vivid-mcp call <tool> '<json>' — 无需 MCP 客户端	Node.js 20+	是

远程（无需安装）

同一 MCP 服务以 Cloudflare Worker 的形式运行在 https://mcp.vividai.tv/mcp（Streamable HTTP，无状态）。每次请求都要发送 API 密钥：

# Claude Code
claude mcp add --transport http vivid https://mcp.vividai.tv/mcp --header "Authorization: Bearer vk_xxx"

// Cursor and other clients that take a URL + headers
{ "mcpServers": { "vivid": { "url": "https://mcp.vividai.tv/mcp", "headers": { "Authorization": "Bearer vk_xxx" } } } }

GET https://mcp.vividai.tv/ 会返回版本和端点。文件必须使用公开 URL（vivid_upload_file 接受 URL）；outputDir / outputPath 会被忽略。

连接器：ChatGPT、Claude.ai（OAuth）

无法发送标头的客户端改用 OAuth 2.1 进行身份验证。添加连接器时，使用 URL https://mcp.vividai.tv/mcp（Claude.ai → Settings → Connectors → Add custom connector）或 https://mcp.vividai.tv/chatgpt（ChatGPT → Settings → Connectors → Create），并选择 OAuth。客户端会发现 /.well-known/oauth-protected-resource，注册自身（动态客户端注册），并将你带到 vividai.tv/oauth/consent，你可在此登录并点击 Authorize。每个连接器都会获得独立凭据（vc_…，绝不是你的 API 密钥），可操作你的资产和额度，但无法更改密码、轮换 API 密钥或删除账户；你可以随时从 Settings → Connected apps 撤销凭据。

/chatgpt 按照 OpenAI 的插件指南提供相同工具：不提供 vivid_buy_credits（额度不足错误会指向说明页面 vividai.tv/credits，该页面没有结账或升级按钮）；不提供 vivid_chat；不接受真人照片或录音作为输入（vivid_create_testimonial 仅接受 attributes，vivid_generate_image 不支持 modelImageUrls，vivid_generate_video 仅接受由 vivid_generate_voice / vivid_generate_music 生成的音频，并且仅接受图库视频作为参考；其他所有图像——帧、参考图、产品和场景照片、修图源文件、vivid_upload_file——都会经过 API 的人物检查，检测到可辨识的人脸时会拒绝处理）。回复不会包含时间戳、原始项目转储、API 路径和提供商详情。

Claude Code 插件（OAuth + 技能）

此仓库也是 Claude Code 插件及其自有市场。它使用 OAuth（无需粘贴密钥）连接远程服务，并添加 skills/ 中的技能（产品照片、产品视频、品牌演员）：

/plugin marketplace add loopotv/vivid-mcp
/plugin install vivid@vivid

然后运行 /mcp，选择 vivid 并进行身份验证：浏览器会打开 vividai.tv/oauth/consent。清单位于 .claude-plugin/；其 version 必须与 package.json 一致（测试会检查这一点），因为只有在版本号变更时，已安装的插件才会更新。使用 claude plugin validate --strict . 检查。

Claude Desktop（一键扩展）

下载 vivid-mcp.mcpb，并用 Claude Desktop 打开：它会使用自带的 Node 运行时安装 MCP 服务，并提示你输入 API 密钥（由 Claude 以机密信息形式存储）。使用 npm run build && npx @anthropic-ai/mcpb pack 从 manifest.json 构建。

本地（npx，Node.js 20+）

Claude Code

claude mcp add vivid -e VIVID_API_KEY=vk_xxx -- npx -y vivid-mcp

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "vivid": {
      "command": "npx",
      "args": ["-y", "vivid-mcp"],
      "env": { "VIVID_API_KEY": "vk_xxx" }
    }
  }
}

Cursor / 其他客户端

使用相同的命令：npx -y vivid-mcp，并在环境中设置 VIVID_API_KEY。

命令行（无 MCP 客户端）

这些工具也可通过内存中的 MCP 客户端从 shell 运行——参数、验证方式和结果都相同。 vivid-studio 技能会在具备终端但没有 MCP 连接的 Agent 中使用此方式。

export VIVID_API_KEY=vk_xxx
npx -y vivid-mcp tools                       # every tool with its title
npx -y vivid-mcp schema generate_image       # description + JSON schema of the arguments
npx -y vivid-mcp call whoami                 # the vivid_ prefix is optional
npx -y vivid-mcp call generate_image '{"prompt":"…","model":"nano-banana-2"}'
npx -y vivid-mcp call edit_timeline @args.json   # or - to read stdin

工具的文本结果会输出到 stdout；工具报告错误时，退出代码为 1。

环境变量

变量	必填	默认值
VIVID_API_KEY	是	—
VIVID_API_URL	否	https://vivid-api.vividoai.workers.dev

示例提示词

• “我在 VIVID 上有哪些视频模型？它们的费用是多少？”
• “用 nano-banana-2 生成 2 张大理石台面上的皮革手提包图片，比例为 4:5。”
• “上传 ~/Desktop/bag.jpg，并使用 Seedance 2.5 将其作为产品参考，制作一个 10 s、9:16 的视频。完成后告诉我。”
• “将我最近的视频下载到 ~/Downloads，并给我一个公开链接。”
• “为产品影片制作一段 30 s 的欢快器乐音乐，并将两个版本都保存到 ./music。”
• “用意大利语转写 ./voiceover.mp3，并将逐词 SRT 写入 ./subs.srt。”
• “根据我最近的两段视频创建一个 9:16 编辑器项目，将每段剪辑到 4 s，中间加入溶解转场，为前 3 s 添加标题 ‘New drop’，然后渲染。”
• “将我最近生成的图片中无名指上的戒指改成素面的黄金戒圈，然后与 ./sku/ring-01.jpg 对比，并告诉我是否通过。”

时间线编辑

vivid_create_editor_project / vivid_edit_timeline 会以无头模式运行 VIVID 编辑器（vivid-editor-core，与网页版编辑器使用相同的 store 和 AI 命令编排器），并将项目保存到你的账户，因此你在此处创建的任何内容都可以在 vividai.tv/tools/editor 中打开，并使用 vivid_render_project 渲染。命令是 { type, payload } 对象（ADD_CLIP、UPDATE_CLIP、SPLIT_CLIP、SET_TRANSITION、SET_CANVAS_PRESET、ADD_TEXT、SET_ANIMATIONS、ADD_EFFECT、SET_MASK……），工具说明中列出了这些命令。媒体可通过 VIVID 资源 ID、URL 或本地路径导入。

UI 录制

vivid_record_ui 会通过 Playwright 驱动本地 Chromium 并录制会话：你需要传入一组步骤（goto、click、hover、type、fill、press、scroll、wait、hide、evaluate，使用 Playwright 选择器），并会获得清晰的 2× 视频（默认视口为 1440×900 时，视频分辨率为 2880×1800），上传到你的图库，可用于 vivid_create_editor_project / vivid_edit_timeline。浏览器会自动登录 VIVID_API_KEY 对应的账户（该密钥会通过 POST /api/me/session 换取一个短时会话），页面内会绘制带点击波纹效果的光标，并会剪掉页面加载的开头部分。步骤可以标记为 optional（缺少对应元素时跳过，例如一次性的引导对话框）。不会扣除点数。

运行 MCP 服务的机器需要安装 Google Chrome（或运行 npx playwright install chromium），且若要输出 MP4，PATH 中需要有 ffmpeg（否则会上传原始 webm，编辑器也能正常渲染）。playwright-core 是可选依赖，仅在使用该工具时加载。

渲染

VIVID 的视频编辑器在浏览器中渲染（Canvas2D + WebCodecs），因此 vivid_render_project 本身不会生成文件：它会排队创建一个渲染任务并返回 openUrl。请在已登录 vividai.tv 的浏览器中打开该 URL（或传入 openBrowser: true，在此机器上打开）——编辑器会加载项目、导出视频并将 MP4 上传到你的图库。vivid_render_status 会报告进度和最终资源；vivid_download_asset 可将其下载。

积分

每次生成都会根据模型扣除 VIVID 积分（每张图片，或视频按每秒积分数 × 时长计费）。vivid_list_models 会显示确切价格；vivid_whoami 会显示你的余额，以及是否已开启自动充值。视频任务启动时会预先扣除积分。

积分来自套餐或积分包（500 / 1,500 / 5,000 积分，售价 €12.99 起，有效期 12 个月，无需订阅）。如果任务执行期间积分用完，失败的调用会返回充值链接：Agent 会显示该链接，你在浏览器中付款，然后 Agent 重试——已完成的工作会保留。vivid_buy_credits 可按需返回同一链接，所需积分会根据仍缺少的积分量计算。开启自动充值后（在 vividai.tv 的 Billing 页面设置），任务不会停止：当积分低于你设定的阈值时，VIVID 会使用你已保存的银行卡再次购买同一积分包，且不会超过你设定的每月上限，每天最多充值 5 次。MCP 中的任何功能都无法从你的银行卡扣款，也无法开启自动充值。

开发

npm install
npm run typecheck
npm test
npm run inspect   # opens the MCP Inspector against the built server

npm run build 会编译到 dist/；从 GitHub 安装软件包时，prepare 脚本会自动运行该命令。

许可证

MIT

Skills

skills/ 存放各个 skill 包（每个文件夹包含一个 SKILL.md，打开 SKILL.md 格式）：

• vivid-studio — 一个 skill 涵盖整个工作室：图像、润饰和 QC、视频、语音、音乐、转录、时间线编辑与渲染、屏幕录制。连接后，SKILL.md 会按领域路由到 references/*.md 并通过 MCP 调用工具；否则会通过上文所述的命令行调用。
• vivid-product-photos、vivid-product-video、vivid-brand-cast — 随 ChatGPT 应用提交的范围更窄的 skill。

它们是基于上述工具的纯指令，不包含自己的代码。 将 skill 文件夹打包为 Zip（cd skills && zip -r vivid-studio.zip vivid-studio），即可发布到 skills 市场。