跳转到文档
v4v.开发者文档预览版您的 API 密钥 ↗
本指南内容
连接你的助手OAuth 2.1 授权ChatGPT(OAuth)Claude WebVS CodeClaude CodeCursorCodex CLIGemini CLIOpenCode其他 MCP 客户端先从简报开始可用工具复用素材库内容并预览成本变体、项目名称和示例整理现有项目媒体和生成获取结果完成 webhook点数和访问权限故障排查Kling 4.0 视频模型GPT-6 Astra 聊天当前图片和聊天模型工作室批量商品视频视频编辑器Gemini text-to-voice样式化文本、字幕与 Google 转录创意合集与代理规划
可供测试
直接访问预览
MCP connection guide

通过您的 AI 助手进行创作。

使用 OAuth 2.1 登录,或通过 API key 连接。探索模型,结合参考媒体进行创作,组装多层编辑,并将完成的视频、图像和音频带入你的对话中。

开始使用 →
端点https://v4v.ai/api/mcp
OAuth
{
  "type": "http",
  "url": "https://v4v.ai/api/mcp"
}
01

连接你的助手#

如需引导式设置,请在 MCP 连接页面选择你的助手。

V4V MCP 让 AI 助手能够发现生成模型、使用参考媒体、创建图片、视频、音频和聊天响应,并检索结果。它使用与 V4V API 相同的账户、点数和生成历史记录。

服务器 URL: https://v4v.ai/api/mcp

传输方式: 可流式传输的 HTTP

身份验证: 在已启用的部署中使用 OAuth 2.1 登录,或在支持自定义请求头的客户端中使用 API 密钥。两种方式都使用你现有的 V4V 账户和点数。

测试其他环境时,请用你的部署域名替换 v4v.ai。服务器已托管,无需在本地运行进程。

使用 OAuth 登录

Choose this option in ChatGPT, Claude, or a supported editor or CLI. You do not need to create an API key. Add the remote server URL, select OAuth / Sign in, and complete the V4V permission screen. See OAuth authorization and the client-specific steps below.

使用 API 密钥连接

  1. 打开你的 V4V 个人资料,并在 API Keys 下创建密钥。
  2. 将 API 密钥保存到你的 MCP 客户端安全设置中。
  3. 使用 x-api-key: YOUR_V4V_API_KEY 或 Authorization: Bearer YOUR_V4V_API_KEY 添加服务器。
  4. 使用 get_balance 或 list_models 连接并开始使用。

发送一个身份验证请求头即可。如果同时发送两者,它们必须包含相同的密钥;凭据冲突或格式错误将返回 HTTP 401。x-api-key 的值就是密钥本身,不带 Bearer 前缀。两种 API 密钥请求头格式使用相同的权限、点数、速率限制和密钥吊销机制。

API 密钥客户端继续使用相同的请求头和权限。OAuth 客户端会通过浏览器登录你现有的 V4V 账户。切勿将密钥或令牌粘贴到与助手的对话中,也不要提交到代码仓库。

02

OAuth 2.1 授权#

  1. Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
  2. Choose OAuth / Sign in. If asked for an OAuth client, select Register automatically (dynamic client registration, or DCR). Leave Client ID and Client Secret empty.
  3. Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
  4. Review the assistant and all three required permissions: view your account and media; upload, estimate costs, edit and share; generate media and transcribe using credits. All three are selected and locked. Choose Accept all permissions, or Cancel to decline.
V4V / MCP connection guide构建值得观看的内容。
  • Return to your assistant, finish connecting if prompted, and ask it to check your balance. Tool permissions and confirmations inside the assistant are managed separately by that client.
  • 助手会从服务器发现 OAuth 端点,并使用 PKCE 完成登录。请不要为此流程创建 API 密钥,也不要粘贴 bearer token。本页顶部的 OAuth 示例仅包含 HTTP 传输和服务器 URL;每个客户端都有自己的配置格式。

    建立连接不会消耗点数。生成任务会使用你现有的 V4V 余额。访问令牌最长有效期为一小时,并会在客户端支持时自动刷新。连接会在 30 天后过期;届时或在撤销访问权限后请重新连接。在 V4V 个人资料 → 助手连接 中管理和断开会话。已提交的任务在断开连接后仍会继续运行。

    如果你的部署不提供 OAuth,请让其运营方启用助手连接,或在兼容的客户端中使用 API 密钥。

    03

    ChatGPT(OAuth)#

    必须先在 V4V 部署中启用 OAuth。ChatGPT 中的账户和工作区权限决定了是否可使用自定义 MCP 连接。

    1. 打开 ChatGPT Plugins → Personal,选择 Add(或 +),然后选择 Add custom MCP server(具体标签可能因账户而异)。
    2. 输入 V4V 和服务器 URL https://v4v.ai/api/mcp。
    3. 选择 OAuth 和动态客户端注册(DCR)。将 Client ID 和 Client Secret 留空;V4V 会自动注册一个公开的 PKCE 客户端。此版本支持 DCR,不支持 CIMD。
    4. 连接并使用你现有的 V4V 登录信息登录。
    5. 在 V4V 的权限页面,检查账户和回调主机。三项权限都为必需:读取账户、编辑/上传,以及使用点数生成。三个复选框均已选中且锁定。选择 Accept all permissions 以连接,或选择 Cancel 以拒绝;不支持部分授权。
    6. 返回 ChatGPT,并在提示时安装插件。在 Personal 插件中,打开 V4V 的三点菜单并选择 Manage。
    7. 打开 Permission 行。若要免审批调用工具,请选择 Allow all tools。生成仍会消耗你的 V4V 点数,因此开始前请先要求估算。
    8. 开始新对话,选择 + → Plugins → V4V(或用 @ 提及它),并输入 Check my V4V balance.

    ChatGPT 截图指南 会带你完成全部八个界面。其中“连接详情”步骤提供插件名称、描述和当前部署服务器 URL 的复制按钮,另可选下载 V4V 图标。

    示例:

    根据这个产品链接创建 3 个竖版 9:16 产品视频创意方案。先展示方案和预计点数。等我批准后再开始生成。

    助手会使用现有的 discovery、estimate_generation 和 generate_studio_variants 工具。估算不会渲染或预留点数,但可能会导入媒体进行校验,因此需要编辑权限。付费工具会在服务器端强制执行生成权限。这里的权限是账户访问权限,而不是对某个具体创意需求的批准:即便如此,在授权渲染前仍应检查所请求的方案和预算。批量 max_credits 和幂等性控制仍然有效。

    访问令牌最长有效期为一小时。刷新令牌会在使用时轮换,连接会在 30 天后过期。过期时或需要额外权限时请重新连接。在 V4V 个人资料 → 助手连接 中,你可以查看使用情况、断开助手连接,或为你的接收端显示其 webhook 签名密钥。不要将签名密钥粘贴到聊天中。

    断开连接会阻止新的工具请求、令牌刷新以及未使用的上传链接。已提交的任务会继续按照现有队列和点数规则运行;断开连接不会取消或退款。此前签发的已签名媒体链接仍保留其正常过期时间。

    来自 ChatGPT 执行环境的文件上传取决于该环境的网络和附件访问能力。带作用域的浏览器上传链接仍可作为后备方案。仅有 MCP 连通性并不保证附件会自动传输。

    自定义连接测试与公开发布插件是两个独立步骤。请参阅 OpenAI 的 MCP 连接指南、OAuth 要求 和 公开审核要求。

    04

    Claude Web#

    OAuth 连接

    打开 Add to Claude。 表单会预先填入 V4V 名称和生产服务器 URL。若用于开发环境或 其他部署,请使用连接页面, 该页面会填入对应部署的 URL。如果登录 Claude 后表单被清空, 请在登录后重新打开该链接。

    请结合 Claude 参照六步截图指南:

    1. 检查预填的名称和 URL,然后选择 Continue。
    2. Claude 会自动检查服务器。保留检测到的 Sign in now 和 Register automatically 设置并选择 Add;无需更改其他设置。将 Client ID 和 Client Secret 留空,不要填写 API 密钥或请求头。
    3. 在连接器页面选择 Connect,然后登录 V4V。
    4. 检查你的账户和全部三项必需权限,然后选择 Accept all permissions。建立连接不会消耗点数。
    5. 在 Tool permissions → Read-only tools 下,打开组名旁边的 Custom,并选择 Always allow。
    6. 滚动到 Write/delete tools,也为该组选择 Custom → Always allow。在对话中启用 V4V,并输入 Check my V4V balance. 生成会消耗你的 V4V 点数;请先要求估算。

    Claude 的工具权限与 V4V 账户授权彼此独立。 组菜单可让你无需逐个修改每个工具就能统一授权。 你可以在 Claude 的连接器设置中调整这些选择。

    Claude 在 claude.ai 和 claude.com 上的托管回调可直接支持, 无需额外的环境配置。请使用 Register automatically;本版本尚未实现 Claude 已发布的 客户端标识(CIMD)。现有的 API 密钥连接仍可按下文所述继续使用。

    如果显示传输设置,请使用 Streamable HTTP。当 Claude 以这种方式呈现时,添加连接器与授权其账户访问是两个独立步骤。

    API 密钥替代方案:创建你的 V4V API 密钥

    打开你的 V4V 个人资料,前往 API Keys,并创建一个密钥。请准备好用于下方连接器请求头。

    2. 添加连接器

    1. Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
    2. Set Name to V4V.
    3. Set MCP server URL to https://v4v.ai/api/mcp.
    4. Under Authentication, select No sign-in.
    5. Click Add header and enter:
    请求头设置值
    名称x-api-key
    值你的 V4V API 密钥,按原样准确复制
    1. 点击 Add / Connect,并等待连接完成。

    在 x-api-key 中仅使用密钥本身,不带 Bearer 前缀。No sign-in 会跳过 OAuth;但该请求头仍会对发送到 V4V 的每个请求进行身份验证。将 OAuth Client ID 和 Client Secret 留空。

    3. 允许工具

    1. 打开 Claude 的 Connectors manager。
    2. 选择新的 V4V 连接器。
    3. 打开 Tool permissions 并允许所有 V4V 工具。
    4. 确认 create_upload_link、get_upload、get_model 和 generate_lab 可用且已启用。

    在 V4V 添加或更新工具后,请先刷新连接器的工具或重新连接,再开始新的对话。

    4. 允许自动上传文件

    1. 打开 Settings → Capabilities。
    2. 如果尚未开启,请启用 Code execution and file creation 和 Allow network egress。
    3. 在 Domain allowlist 中,添加以下条目:
    text
    v4v.ai
    *.v4v.ai
    *.v4vcdn.space

    请同时保留根域名和通配符条目,以覆盖应用域名及其子域名。仅输入域名,不要带 https:// 或 /api/mcp,然后保存更改。如果你的工作区集中管理此设置,请让管理员更新允许列表。

    这样可让 Claude 的执行环境使用 MCP 签发的短时上传权限,将原始附件直接发送到 V4V。没有此设置时,连接器可能可以工作,但文件上传会因 host_not_allowed 而失败。

    **在 dev 上测试:**使用 https://h4000.kitpes.com/api/mcp 作为连接器 URL,并将 h4000.kitpes.com 单独添加到 Domain allowlist。V4V 的域名条目不包含 dev 主机名。

    5. 开始新的对话

    在新聊天中启用 V4V 连接器,附加你的图片,然后输入:

    用 V4V 将这张图片放大 4 倍。自动上传原始文件,然后用它的文件 ID 搭配 Topaz 模型。

    Claude 应通过 MCP 获取上传权限,从其执行环境传输文件,而不是将 base64 复制到聊天中,然后提交生成任务。在允许网络访问时,你无需再在单独的浏览器页面中重新上传该文件。

    关于 Claude 的通用连接器和网络控制,请参阅连接器管理和代码执行与网络访问。

    05

    VS Code#

    OAuth 登录

    在连接页面中使用 Install in VS Code,或将以下内容添加到 .vscode/mcp.json:

    json
    {
      "servers": {
        "v4v": {
          "type": "http",
          "url": "https://v4v.ai/api/mcp"
        }
      }
    }

    启动服务器,查看信任提示,并在 VS Code 打开浏览器时完成 V4V 登录。在代理聊天中启用你要使用的工具。

    API 密钥替代方案

    对于编辑器聊天,将以下内容添加到 .vscode/mcp.json。VS Code 会提示输入密钥并隐藏输入内容。请在文件中保留该占位符。

    json
    {
      "inputs": [
        {
          "id": "v4v-api-key",
          "type": "promptString",
          "description": "V4V API key",
          "password": true
        }
      ],
      "servers": {
        "v4v": {
          "type": "http",
          "url": "https://v4v.ai/api/mcp",
          "headers": {
            "Authorization": "Bearer ${input:v4v-api-key}"
          }
        }
      }
    }

    从 MCP 配置启动服务器,并在你的聊天会话中启用其工具。在允许其消耗点数前,请检查生成工具调用。

    对于其他 VS Code 代理环境,请按照当前 MCP 配置参考中该环境支持的配置位置进行设置。

    06

    Claude Code#

    OAuth 登录

    注册远程服务器时不要添加身份验证请求头:

    bash
    claude mcp add --transport http v4v https://v4v.ai/api/mcp

    启动 Claude Code,运行 /mcp,选择 V4V 并进行身份验证。在浏览器中完成 V4V 权限页面后,返回 CLI。

    API 密钥替代方案

    在 shell 环境中安全地设置 V4V_API_KEY,然后注册远程服务器:

    bash
    claude mcp add --transport http \
      --header "x-api-key: $V4V_API_KEY" \
      v4v https://v4v.ai/api/mcp

    在 Claude Code 中使用 /mcp 检查连接。注册会将配置好的请求头存储在你的本地客户端配置中;请保护该文件,并不要将其纳入源代码管理。有关配置范围和密钥管理,请参阅 Claude Code 的 MCP 指南。

    07

    Cursor#

    在连接页面中,选择 V4V 登录或 API 密钥, 然后点击 Install in Cursor。在接受前,请先在 Cursor 中检查安装内容。 OAuth 会打开浏览器登录;API 密钥设置会安装一个占位符,你需要在本地的 .cursor/mcp.json 中替换它。安装 URL 中不会嵌入真实密钥。 当前桌面版本使用 HTTP 回环回调;云客户端使用精确批准的 https://www.cursor.com/agents/mcp/oauth/callback URI。

    08

    Codex CLI#

    对于 OAuth,添加服务器并登录:

    bash
    codex mcp add v4v --url https://v4v.ai/api/mcp
    codex mcp login v4v

    对于 API 密钥,请先在环境中安全地设置 V4V_API_KEY,然后运行:

    bash
    codex mcp add v4v --url https://v4v.ai/api/mcp --bearer-token-env-var V4V_API_KEY
    09

    Gemini CLI#

    使用 gemini mcp add --transport http v4v https://v4v.ai/api/mcp 添加远程服务器。 在 Gemini CLI 中运行 /mcp auth v4v 进行 OAuth。对于 API 密钥设置,请安全地设置 V4V_API_KEY,然后使用 gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp 添加服务器。 CLI 会保存已配置的请求头;请妥善保管其设置的私密性。

    10

    OpenCode#

    在 opencode.json 中的 mcp.v4v 下添加一个远程服务器,使用 type: "remote"、 url: "https://v4v.ai/api/mcp" 和 enabled: true。运行 opencode mcp auth v4v 进行 OAuth。连接页面 提供完整的 JSON,以及基于环境变量的 API 密钥替代方案。

    11

    其他 MCP 客户端#

    选择 remote / Streamable HTTP 服务器,并提供:

    设置值
    名称v4v
    URLhttps://v4v.ai/api/mcp
    身份验证(任选其一)x-api-key: YOUR_V4V_API_KEY 或 Authorization: Bearer YOUR_V4V_API_KEY

    不同客户端的配置格式各不相同。请在客户端的密钥设置中配置请求头,而不是在聊天消息中配置。不支持仅支持旧版 SSE 的客户端。受支持的原生 OAuth 客户端使用 localhost 或 127.0.0.1 上带显式本地端口的 HTTP 回调。注册和授权会严格绑定完整的回调 URL。Claude、ChatGPT、Cursor 和 VS Code 的托管回调已获批准;其他托管客户端需要在 MCP_OAUTH_REDIRECT_URIS 中提供精确 URL。

    12

    先从简报开始#

    对于完整影片或对现有录制内容进行创意重剪,请在组装或付费工作开始前先补齐会产生重要影响的缺失选择:目标、受众、源素材、格式、目标时长、视觉处理、字幕、语音、音乐和输出语言。get_started 接受 request_kind(production、creative_edit、targeted_edit)和已确认的 creative_brief 选择;它会返回 videoBrief.productionQuestions 和 readyForProduction。请复用已提供的回答和明确授权委托的部分。精确剪辑或修正只需提供与该变更相关的细节。自动批准支出并不等于提供创意答案。这些规则由 V4V MCP 和 Open Video Kit 0.3.6 共用。

    你可以这样开始请求:

    为我的陶瓷马克杯找一个适合生成八秒竖版视频的模型。使用这张产品图片:https://example.com/mug.jpg.。先向我展示一个概念和生成所需的输入,再开始生成。

    如果未指定模型,助手默认必须使用 Google/Gemini Omni Flash v1.2(video.gemini_omni_flash-1-2),通过 get_model 检查其当前 schema 和可用性,检查余额,并准备输入。等你请求生成后,它会提交任务并检查是否已完成结果。此规则在 MCP 初始化说明中排在首位,并在 list_models、get_model 和 generate_lab 的描述中重复说明。视频模型发现会返回 default_video_model;所选模型会公开 default_for_unspecified_video: true。明确指定的模型或 Studio/批量工作流选择优先。

    对于普通视频请求,如果未明确指定模型,优先使用带有 video.gemini_omni_flash-1-2 的 generate_lab。助手不应仅因用户未指定模型就要求用户选择模型。明确的模型选择和明确请求的 Studio/批量工作流优先。选择输入和参数前仍然必须先有 get_model;如果首选模型被禁用、不可用或不适合,应说明限制并询问可替代方案,而不是悄悄把点数花在别处。提供商路由由 V4V 配置,不是生成参数。对于明确请求的 Studio 工作流,请使用 generate_studio;图像、音频、翻译和聊天发现保持不变。

    video_brief 提示有助于将目标、受众和格式转化为分镜计划。v4v://guide 资源会向你的助手说明生成工作流。

    13

    可用工具#

    工具用途是否创建生成任务?
    list_models发现已启用的模型;可选择按图像、视频、音频或聊天进行筛选否
    get_model读取模型的输入、选项和限制;model: "studio" 同样适用否
    describe_studio发现当前工作室的风格、时长、格式、质量、声音和媒体限制否
    list_products查找已拥有的产品;将其 ID 复用为工作室 input.product_id否
    list_avatars查找已拥有及公开激活的虚拟形象;将 ID 复用为工作室 input.avatar_id否
    estimate_generation在不渲染或预占点数的情况下验证并报价实验室/工作室请求否
    get_balance查看账户可用点数否
    get_usage查找近期生成任务否
    get_file检查已拥有的参考文件否
    import_media将公开媒体 URL 保存到您的素材库否
    create_upload_link发起有范围限制的 HTTP 上传请求;浏览器链接可作为备用方式否
    get_upload获取上传状态和文件 ID否
    upload_media以编程方式内联上传字节数据;避免在模型文本中使用大型 base64 内容否
    generate_lab使用指定模型进行创建是——消耗点数
    generate_studio根据产品或创意简报生成视频是——消耗点数
    get_task查看状态、项目 ID、稳定媒体 ID 及可续期签名链接否
    refresh_task_results在不重新渲染的情况下续期已签名的结果 URL否
    list_projects按标题、来源或文件夹查找已拥有的工作室、工作流、实验室及排队中的 API 项目否
    rename_project重命名已拥有的项目或排队任务的未来项目否
    list_project_folders列出项目工作区中显示的相同文件夹否
    create_project_folder创建工作区文件夹否
    rename_project_folder重命名文件夹同时保留其中的项目否
    move_project分配已拥有的文件夹,或使用 folder_id: null 取消归档否
    generate_studio_variants使用现有批量预算和控制项排队生成 2–3 个创意变体是——随变体启动时消耗
    promote_to_example仅限示例管理员:以明确的可见性复制/更新已拥有项目的示例否

    Studio 发现会从此部署中读取所选工作流和当前启用的样式;它不会硬编码七个样式名称,也不会假设每个工作流都有十秒时长限制。带有 model: "studio" 的 get_model 是 describe_studio 的别名。对于无法读取 v4v://guide 的客户端,关键说明也写在工具描述中。

    模型 schema 来自与 V4V LAB 相同的目录。选择参数前先请求 get_model;所需参考、时长和格式因模型而异。

    14

    复用素材库内容并预览成本#

    调用 list_products 或 list_avatars(可选 offset 和 limit,最大 100)。数字人默认使用 source: "all";也可使用 owned 和 public 筛选。返回的 next_offset 在最后一页时为 null。公开数字人 ID 包含 public:;请保留此前缀。每条记录都包含 photo_count;Studio 会使用数字人的主照片。返回的仅是你自己的私有素材库记录。

    在 generate_studio 或 estimate_generation 中使用 input.product_id 和 input.avatar_id。parameters.avatar 也接受返回的数字人 ID,并继续支持文件 ID 或公开图片 URL。请选择 input.avatar_id 或 parameters.avatar 其中之一。素材库照片会被直接解析,无需再次下载再上传。明确提供的产品名称、描述或图片输入会覆盖已保存产品的默认值。启用中的样式 ID/名称会使用其已保存的创意说明;未知或未启用的样式 ID/名称会返回带有 allowed_values 的 INVALID_PARAMETER。将自由形式的创意指令放入 input.prompt,并选择一个启用中的预设(或省略样式以使用发现到的默认值)。

    json
    {
      "source": "studio",
      "input": {
        "product_id": "0123456789abcdef01234567",
        "avatar_id": "public:0123456789abcdef01234568",
        "prompt": "A short product review"
      },
      "parameters": {
        "duration": 10,
        "style": "Product Review"
      }
    }

    将其发送到 estimate_generation。它会返回 credits_estimated,预留点数为零,也不会创建任务或渲染。Studio 报价会跳过提供商角色注册,即使选择了数字人也是如此。可导入公开媒体 URL 进行验证。报价会随输入/价格变化;聊天报价描述的是初始预留,而不是最终 token 成本或支出上限。要渲染,请移除 source,并将相同输入连同新的 idempotency_key 提交到 generate_studio。

    15

    变体、项目名称和示例#

    generate_studio_variants 接受 name、共享的 input/parameters、必填的 max_credits、idempotency_key,以及包含两个或三个对象且可选择覆盖输入/参数的 variants。例如:variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]。每个变体都是一次单独的付费尝试。这是对现有 Studio 批处理队列的封装:它返回 batch_id,使用 get_studio_batch 获取结果,并使用相同的暂停/预算/返工控制。它绝不会绕过容量限制。

    使用 rename_project,传入由 list_projects、生成或 get_task 返回的 project_id,以及 project_name(去除首尾空白后 1–200 个字符)。重命名还会更新任务标题和 LAB 历史记录,即使项目仍在等待创建时也是如此。它不会更改原始幂等请求哈希。

    只有示例管理员才能发现 promote_to_example。它接受一个已保存结果的、已拥有的 project_id、必填的 active 和 surfaces: ["dashboard", "studio", "landing"](可任选任意子集)。studio 映射到现有的 ProVid/Studio 可见性标志。无论选择了哪些展示界面,active: false 都会在所有地方隐藏该示例。结果中包含 visible_on,因此实际可见性一目了然。发布需要用户提出请求;此工具不会消耗生成点数。

    16

    整理现有项目#

    使用 list_projects 查找现有项目而不进行生成。它包含 Studio、工作流、LAB 历史记录和排队中的 API 项目。可选筛选条件:source: "all" | "studio" | "workflow" | "lab"、用于字面标题搜索的 q,以及用于已拥有文件夹或 "unfiled" 的 folder_id。省略文件夹筛选即可查看所有项目。list_projects 和 list_project_folders 都接受 offset(默认 0)和 limit(1–100,默认 50);持续跟随 next_offset,直到其为 null。

    例如,要整理已批准的广告活动结果:

    1. 使用 {"q":"approved"} 调用 list_projects,并选择目标项目。
    2. 调用 list_project_folders;复用目标文件夹,或使用 {"name":"Summer campaign"} 调用 create_project_folder。
    3. 对每个已选 project_id,使用返回的 folder_id 调用 move_project。
    4. 使用该 folder_id 调用 list_projects,验证文件夹内容。

    使用带有 folder_id: null 的 move_project 将项目从其文件夹中移除。rename_project_folder 接受 folder_id 和 name。文件夹名称在去除首尾空白后必须包含 1–80 个字符,并且在你的账户中必须唯一;重复时会返回 FOLDER_NAME_CONFLICT。如果创建后的响应不确定,请先列出文件夹再重试。移动和重命名操作可安全重复执行,不会消耗点数、生成媒体或更改结果。排队中的项目在工作器创建它们时会保留其名称和文件夹。这些操作无法访问其他账户的项目或文件夹。

    17

    媒体和生成#

    参考媒体可以是公开 URL,也可以是你拥有的 V4V 文件 ID。名为 image_url 的字段也接受文件 ID;请使用模型 schema 来选择准确的输入字段。

    自动上传附件和本地文件

    当助手的执行环境可以访问此 V4V 部署时,助手可以自行上传原始文件。你无需把 API 密钥复制到聊天中,也无需再次选择同一个文件。

    1. 调用 create_upload_link。尽管其名称如此,该工具还会返回 upload_request:一个 POST URL、一个带作用域的 x-upload-token 请求头,以及 multipart 字段名 file。
    2. 通过助手的执行工具,使用 multipart/form-data 将实际的本地文件字节发送到该 URL。让 HTTP 客户端自行设置 boundary,并禁用重定向。不要转换图片,也不要在对话中输出 base64。
    3. 读取响应中的 file_id,并使用 upload_id 通过 get_upload 进行确认。
    4. 发现模型的输入 schema,将该 ID 传入其媒体字段(例如 Topaz image_url),然后提交所请求的生成。
    5. 如有多个参考,请为每个所需文件分别使用单独的上传槽位重复此过程。

    上传令牌会在 15 分钟后过期,接受一个文件,大小上限为 20 MiB(受服务器限制约束),且不能读取你的素材库,也不能消耗生成点数。实际字节通过 HTTP 传输;MCP 提供带作用域的授权并控制生成。

    对于执行环境中可通过 slot 获取工具结果的情况,二进制传输如下:

    python
    import requests
    
    upload = slot["upload_request"]
    with open(local_file_path, "rb") as source:
        response = requests.post(
            upload["url"],
            headers=upload["headers"],
            files={upload["file_field"]: (filename, source, content_type)},
            allow_redirects=False,
            timeout=120,
        )
    if response.status_code != 200:
        raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
    file_id = response.json()["file_id"]

    在 Claude 中允许上传主机名

    MCP 连接性和沙箱网络访问是分开的。host_not_allowed 表示沙箱无法发送二进制上传,即使 MCP 调用本身可以正常工作。

    按照上方的 Claude Web → Allow automatic file uploads 操作:打开 Settings → Capabilities → Domain allowlist,添加 v4v.ai、*.v4v.ai 和 *.v4vcdn.space,并启用网络出站访问。开发环境还需单独添加 h4000.kitpes.com。由工作区管理的限制可能需要管理员进行更改。

    助手必须在第一次请求被拒绝后立即停止,并说明所需设置,而不是持续重试几分钟或把文件转成模型文本。更新权限后请开启新的对话,并在服务器更新后刷新连接器的工具。

    可选的浏览器回退方案

    如果你选择手动上传,请打开 upload_url,选择原始文件,并在准备就绪后告诉助手。助手会通过 get_upload 获取文件 ID。这只是回退方案,不是自动 HTTP 上传可用时的必需步骤。

    upload_media 仍可用于以编程方式转发字节,或处理编码后不超过 8 KiB 的极小负载。其解码后 5 MiB 的服务器限制,并不代表适合语言模型文本传输的预算。不要仅为了传输而缩放/重压缩源文件,不要输出大型 base64 字符串,也不要循环传输编码分块。

    用于大文件的 REST 上传

    如果助手的执行环境具有出站网络访问能力,并配置了安全的 API 密钥,它可以通过 POST /api/v1/files 使用 multipart 字段 file 进行上传。MCP 连接器的密钥不会自动提供给 shell 工具。

    bash
    # V4V_BASE_URL is this deployment's origin, e.g. https://h4000.kitpes.com
    curl "$V4V_BASE_URL/api/v1/files" \
      -H "Authorization: Bearer $V4V_API_KEY" \
      -F "file=@/path/to/photo.png"

    响应中的 id 就是要在生成输入中使用的文件 ID。让 curl 自行设置 multipart boundary。请将凭据保存在安全的客户端配置中,而不是放在对话里。

    公开 URL

    使用 import_media 保存可访问的媒体 URL 以便复用,或直接将该 URL 提供给模型。不要把本地路径或沙箱 URL 当作公开 URL 传入。

    generate_lab 的示例参数(请将示例 ID 替换为你上传后返回的 ID):

    json
    {
      "model": "image-upscale-topaz",
      "project_name": "Product detail — enlarged",
      "input": {
        "image_url": "0123456789abcdef01234567"
      },
      "parameters": {
        "upscale_factor": "2"
      },
      "idempotency_key": "product-detail-upscale-001"
    }

    generate_studio 的示例参数:

    json
    {
      "project_name": "Ceramic mug — launch video",
      "input": {
        "product_name": "Ceramic mug",
        "product_description": "A handmade mug with a matte glaze",
        "product_images": [
          "https://example.com/mug.jpg"
        ],
        "prompt": "A calm product reveal in soft morning light"
      },
      "parameters": {
        "duration": 8,
        "aspect_ratio": "9:16"
      },
      "idempotency_key": "mug-launch-video-001"
    }

    每次有意发起生成时,都要使用新的 idempotency_key。如果请求因网络中断而重试,请复用相同的 key 和参数。使用相同 key 但输入已变更时,会返回冲突。

    18

    获取结果#

    生成工具会立即返回 task_id 和 project_id。如果账户并发上限已满,同一任务会以 credits_reserved: 0、credits_estimated 和 queue 详情进入等待,其中包含已配置的上限、5 秒检查间隔以及 estimated_start_at: null。完成时间无法预测。不要为了绕过等待而再次提交生成。工作器会在有空闲槽位时预留点数;如果当时余额不足,任务会在准入阶段失败,并发送其配置的 webhook。它们不会在渲染完成前一直保持会话打开。

    json
    {
      "task_id": "task_6aa962444bd1dd7ab65bc6b6"
    }

    将该 ID 传给 get_task。两次检查之间至少等待 5 秒。任务状态可能是 queued、processing、completed、failed 或 cancelled。

    当状态为 completed 时,results 会包含用于聊天的内联文本,或用于媒体的签名下载 URL。助手可以将这些 URL 分享给你,而不需要浏览器 cookies。如果链接过期,请使用 get_task 或 refresh_task_results。媒体结果包含稳定的 asset_id/file_id;在未来生成的媒体字段中,应直接传入 file_id,而不是复制会过期的 URL。次日复用约定是:在文件仍存在且访问仍被允许时,提供稳定 ID 加可续期链接;URL 本身可以过期。链接会保持签名;切勿移除签名,也不要推导未签名的 CDN 路径。出现任何终态状态后都应停止轮询。检查任务绝不会启动第二次生成。失败任务会在已知情况下报告 error.stage、brief_completed、retryable 和建议的 retry_after_seconds,并同时附带实际的 credits_used。即使视频生成失败,已完成的 brief 也可能保留其扣费。retryable: true 表示可能是暂时性错误;这并不授权再次发起付费尝试。如果任务返回 GENERATION_SERVICE_ERROR,说明模型服务报告了内部故障。不要假定是源分辨率或缩放系数导致,也不要自动切换模型或创建新的付费尝试。请说明失败情况,并等待用户请求重试。

    LAB 生成也会显示在 LAB → 历史运行 和 项目 中。你的 API key 使用情况会显示在个人资料中。

    19

    完成 webhook#

    generate_lab 和 generate_studio 支持 callback_url,沿用现有 REST webhook 投递与签名校验。V4V 会发送 task.completed 或 task.failed,其中包含稳定的 event_id、任务数据、点数和结果。请使用创建 API key 时显示的 webhook 签名密钥来验证 X-V4V-Timestamp 和 X-V4V-Signature,并按 event_id 去重。不要把密钥粘贴到聊天中。投递重试不会创建新的生成。回调 URL 使用与 REST 相同的外部网络校验。批量提交和变体提交也支持 callback_url 以接收已签名的批处理事件;请参见下方监控工作流。参见 REST webhook verification。

    20

    点数和访问权限#

    生成会使用你正常的 V4V 点数。对于普通的 LAB/工作室任务,在有可用容量时会预留预计费用;超出的任务会在不预留费用的情况下等待。未使用的点数遵循与 REST API 相同的释放规则。查询模型、余额、任务和现有文件不会消耗生成点数。

    每个工具都限定在所配置 key 的所有者范围内。无法访问其他账户的文件和任务。你可以在个人资料中撤销某个 key,以禁用其 MCP 连接。工具注解会标识哪些调用会创建工作并消耗点数,以便你的客户端提供其常规的工具审批控制。

    21

    故障排查#

    症状检查项
    缺少 create_upload_link 或 upload_media刷新或重新连接 MCP 连接器,让客户端重新发现已更新的工具列表
    HTTP 401在 x-api-key 中使用有效且未撤销的 key,或使用带有 Bearer 前缀的 Authorization;移除冲突的请求头
    HTTP 403对于基于浏览器的客户端,其 Origin 必须在部署中被允许
    浏览器中出现 HTTP 405该端点接受 MCP POST 请求;请使用 MCP 客户端
    HTTP 406客户端必须同时接受 application/json 和 text/event-stream
    HTTP 429 / RATE_LIMIT_EXCEEDED读取 JSON 中的 error.retryable 和 retry_after_seconds;请求窗口限制还包括 scope 和 limit。按要求等待,并对被拒请求复用相同的 request/idempotency key。已经失败的任务会保持终态。账户和 key 限制与 REST 共享。
    工具结果包含 isError: true读取结构化错误,修正输入,避免盲目重试生成
    模型输入被拒绝刷新 get_model 并使用其当前 schema
    任务长时间处于排队或处理中继续间隔检查;不要自动提交替代生成

    该服务使用官方 MCP TypeScript SDK,并通过 Streamable HTTP 采用无状态 JSON 响应模式。有界等待工具会在有更新或超时前保持单次请求处于打开状态;它们不会建立永久通知通道。客户端会在连接时协商协议版本。

    GPT Image 2.5 图片变体

    模型发现包括 Flare 和 Sunburst 文本/图片变体,其中 image.text_to_image 和 ai.image_edit 默认使用 Sunburst。它们支持 background、1K/2K/4K 定价(6/10/16 点数)、最长 20,000 个字符的提示词,以及最多 16 张编辑图片。变体 ID 和宽高比限制请参见 GPT Image 2.5 settings and API examples。

    22

    Kling 4.0 视频模型#

    四个独立节点在实验室、工作流、API 和 MCP 中共享相同的生成与结果处理方式:

    目录 ID模型时长分辨率
    video.kling_v40_refKling 4.0 Reference3–30 秒720p / 1080p
    video.kling_v40_keyKling 4.0 Keyframe3–30 秒720p / 1080p
    video.kling_v40_flash_refKling 4.0 Flash Reference3–20 秒720p
    video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 秒720p

    全部都接受必填的 prompt(最多 8000 个字符)、整数 duration、resolution 和 aspectRatio(auto、16:9、9:16、1:1、21:9;Flash Keyframe 不包含 auto)。全部都可以仅从文本生成。Reference 输入为可选。

    Reference 模型接受 referenceImageUrls(最多 10 个)、referenceVideoUrls(最多 5 个)、elements(最多 7 个,若含视频则最多 3 个)和 keepOriginalSound。一个命名元素包含 name、imageUrls(2–4 张图片)或 videoUrl(一段 3–8 秒的角色片段)二选一、可选的 tag、description(100 个字符)以及角色 voiceUrl。Flash 还接受元素 type(image 或 video)。标准 Reference 还接受 voices:最多 3 个对象,每个包含 name 和 audioUrl。Flash 则改为将声音绑定到角色元素。

    图片、视频参考、元素和独立声音合计最多 15 个;参考视频与视频元素合计不能超过 5 个。每个参考视频必须为 2–30 秒(Flash 为 2–20 秒),且它们与视频元素合计的总时长最多为 30 秒(Flash 为 20 秒)。名称在忽略大小写时必须唯一,且为 1–20 个中文字符、字母、数字或下划线;内置参考名称为保留名称。请将提供的参考写作 @image_1、@video_1 或它们声明的 @name。未声明的提及将被拒绝。

    Keyframe 模型使用 firstFrameUrl。标准 Keyframe 还接受有序的 keyframeUrls(最多 8 个中间帧)和 lastFrameUrl;这些都要求提供首帧。总帧数不能超过 min(duration + 1, 10)。Flash Keyframe 仅支持首帧。提及帧时请使用 @first_frame、@keyframe_1、@last_frame。基于帧的输出会遵循首张图片的宽高比。

    所有媒体字段(包括嵌套的元素和声音)在 API/MCP 中都接受 URL 或你拥有的 V4V 文件 ID。工作流图片/视频端口使用 reference_image_urls / reference_video_urls,或 first_frame_url / keyframe_urls / last_frame_url;提示词使用 script-in。标准 Reference 还支持在 voice_audio_urls 上传音频,并声明为 @voice_1、@voice_2 等。两个工作流输出都是标准的 video / clips,适用于现有渲染器和编辑器。API/MCP 会返回常规的异步任务和可下载结果文件;请轮询任务或使用完成 webhook。

    以下为经批准的基础费率,单位是每秒消耗的 V4V 点数,未包含管理员覆盖或现有工作流调整。这些费率会被直接使用,不进行 USD 换算,也不添加零售加价:

    模型720p,无视频720p,有视频1080p,无视频1080p,有视频
    Standard Reference28.51742.525.5
    Standard Keyframe28.5不可用42.5不可用
    Flash Reference1711.3不可用不可用
    Flash Keyframe17不可用不可用不可用

    5 秒输出示例:

    模型5 秒,无源视频5 秒,含最多 5 秒源视频
    Standard Reference,720p142.5 点数170 点数
    Standard Reference,1080p212.5 点数255 点数
    Standard Keyframe,720p / 1080p142.5 / 212.5 点数不可用
    Flash Reference,720p85 点数113 点数
    Flash Keyframe,720p85 点数不可用

    没有视频输入时,计费秒数等于输出秒数。有参考视频或视频元素时,计费秒数等于 max(total input video seconds, output seconds) + output seconds,并按对应的视频输入费率计费。例如,10 秒 1080p 的 Standard Reference 输出,如果输入总时长为 15 秒,则计费 25 秒,调整前为 637.5 点数。会保留小数点数;完整费用只会统一四舍五入一次,保留两位小数。若输入时长未知,为进行保守估算,会使用模型允许的最大输入时长;服务器会在扣费前校验实际源时长。请使用与生成相同的输入来请求当前报价。管理端可为每个节点分别设置分辨率/视频输入费率。较旧的 Kling 节点会保留其现有价格和设置。

    json
    {
      "model": "video.kling_v40_key",
      "input": {
        "prompt": "Move from @first_frame to @keyframe_1 and finish at @last_frame",
        "firstFrameUrl": "https://example.com/start.png",
        "keyframeUrls": [
          "https://example.com/middle.png"
        ],
        "lastFrameUrl": "https://example.com/end.png"
      },
      "parameters": {
        "duration": 5,
        "resolution": "1080p",
        "aspectRatio": "16:9"
      }
    }

    在 MCP 中配合 generate_lab 使用此请求体,在 HTTP 中则配合 POST /api/v1/lab。若要获取报价,请添加 "source": "lab",并在 MCP 中使用 estimate_generation,或在 HTTP 中使用 POST /api/v1/generation/quote。务必先通过 get_model 或 GET /api/v1/models/{id} 发现所选模型。标准的生成授权、余额检查、幂等 key、回调和失败退款规则同样适用。

    23

    GPT-6 Astra 聊天#

    先将 list_models 与 {"type":"chat"} 搭配使用,再将 get_model 与 {"model":"chat.gpt_6_astra"} 搭配使用,以检查当前输入、token 费率和取整方式。使用 generate_lab 提交:

    json
    {
      "model": "chat.gpt_6_astra",
      "input": {
        "prompt": "Explain this idea in three sentences."
      },
      "parameters": {
        "reasoningEffort": "low",
        "webSearch": false,
        "stream": false
      },
      "idempotency_key": "astra-question-001"
    }

    Optional input.imageUrls accepts up to 12 public URLs or owned file IDs. Text-only requests use string input upstream; images use the model’s multimodal message array. Optional input.functionTools accepts a JSON string of function definitions; web search must be off when functions are present. Function selection is automatic, and completed task results include function_calls for the caller to handle. The model node does not execute functions. Poll get_task using the returned task ID. Completed results entries have type: "text", text, usage, credits and incomplete instead of a download URL.

    聊天会先预留 1 点数。最终费用基于实际输入、缓存和输出 token 计算,向上取整为整数点数,且至少为 1。超出预留金额的部分会在响应后扣除;初始预留并不是消费上限。token 费率由 get_model 公布。因网络原因重试时,请复用相同的 idempotency key 和参数;失败后不要自动再次提交新的付费生成。

    对于按用量计费的聊天和图片生成,estimate_generation 还会返回以 V4V 点数表示的 credits_range.min 和 credits_range.max,其中已包含加价和当前价格调整。请将其展示为大致范围。它的 assumptions 用于描述示例性使用场景;实际费用可能超出该范围,且 is_spending_cap 为 false。credits_estimated 和 initial_reservation_estimated 仍然是单独的初始预留估算。此预览不会预留点数,也不会启动生成。

    24

    当前图片和聊天模型#

    Omni Flash 1.2 is the default for an unspecified video request; 1.1 remains available by explicit selection. Use get_model for image.text_to_image or ai.image_edit to discover GPT Image 2.6 Flare, Sunburst and Economy variants. Pass parameters.outputFormat and respect allowed_by_variant: Flare/Sunburst text-to-image support PNG/JPEG/WebP/GIF/SVG; their image-to-image variants support PNG/JPEG/WebP; Economy text supports PNG/GIF and Economy image supports PNG. Output downloads preserve GIF frames and SVG vector bytes. SVG conversion usage is included in final billing.

    Nano Banana 2.1(parameters.variant: "nano-banana-v2.1")支持 1K/2K/4K,以及最多 10 个参考。请读取 pricing_by_variant 以获取其当前计费模式。Google/Vertex 生成会按实际输入、缓存输入、图片输出、文本输出和思考 token 结算,并包含加价;其他路由使用已配置的图片费率。Gemini 4 Argon(chat.gemini_4_argon)会将思考 token 计入用量计费。请使用 estimate_generation 展示大致点数范围;初始预留和范围都独立于最终实际用量,也都不是消费上限。切勿虚构路由参数,也不要静默更改管理设置。

    25

    工作室批量商品视频#

    当你想为一组商品生成视频时,请使用 generate_studio_bulk。它接受 1–300 个条目,并立即返回一个 batch_id。它与 REST 和 Web 应用共享账户的常规点数余额,以及共享的 V4V 生成队列。

    json
    {
      "name": "Autumn product videos",
      "input": {
        "prompt": "Show three benefits in a calm product reveal"
      },
      "parameters": {
        "duration": 8,
        "aspect_ratio": "9:16"
      },
      "max_credits": 600,
      "test_count": 5,
      "items": [
        {
          "sku": "MUG-01",
          "product_id": "0123456789abcdef01234567"
        },
        {
          "sku": "BAG-02",
          "product_url": "https://shop.example/products/bag?variant=blue"
        },
        {
          "sku": "LAMP-03",
          "input": {
            "product_name": "Desk lamp",
            "product_images": [
              "https://shop.example/lamp.jpg"
            ]
          },
          "parameters": {
            "style": "TV Spot"
          }
        }
      ],
      "idempotency_key": "autumn-products-001"
    }

    条目输入和参数会覆盖共享设置;其余部分由工作室默认值补足。可提供你拥有的商品 ID、公开的商品页面 URL,或已准备好的商品详情和媒体。请使用当前部署的工作室模型所支持的设置。省略 test_count 可处理整个列表。使用 test_count: 5 时,前五个条目(若不足五个则为全部条目)会先运行,之后批次会暂停以供审核。

    工具用途是否消耗生成点数?
    generate_studio_bulk创建商品视频批次,并要求提供点数预算是,随着每个条目开始而消耗
    list_studio_batches列出该账户的最新批次否
    get_studio_batch读取分页进度、条目任务 ID、结果和稳定的 state_token否
    wait_studio_batch等待状态变化、完成、暂停或取消;默认 25 秒否
    control_studio_batchpause、resume、cancel、retry_failed、rework 或 restart;可选的 max_credits 会增加累计预算恢复和新尝试可能会消耗点数

    DIRECTOR_REQUEST_FAILED 表示 AI Director 文本请求被拒绝;REFERENCE_MEDIA_UNAVAILABLE 表示读取其参考文件时出现问题。请说明失败所处阶段并报告任务 ID;切勿假定这表示视频生成请求失败,也不要自动创建新的付费尝试。

    公开的 eBay 商品 URL 支持受保护浏览器导入回退。如果店铺仍然拒绝导入,请发送你拥有的 product_id 或准备好的商品详情/图片。IMPORT_FAILED 会在付费受理前发生,并包含已知的导入原因;PREPARATION_FAILED 用于标识后续的准备失败。失败的尝试会保持为终态。当用户要求重试时,使用 control_studio_batch 并传入 action: "retry_failed" 和新的 idempotency_key;还可选提供从零开始的 item_indexes。对于已更正的输入或有意重新制作,请使用 action: "rework" 并传入 items: [{task_id: "task_…", input: {prompt: "New direction"}}](或用 index: 1 代替 task_id)。仅当用户要求将所有条目都重新执行一次(包括成功项)时,才使用 action: "restart"。这三种操作都要求每次有意执行时使用新的 key;遇到网络错误时,重放相同的 key 和参数。resume 不会重试失败的尝试。

    如果只想重做你不满意的结果,请选择它们当前的 items[].task_id,然后调用 control_studio_batch,传入 action: "rework"、items 中的这些 ID,以及新的 idempotency_key。省略输入更改即可按相同简报重新运行。所选当前结果会立即清除,同一批次会恢复处理;其他已完成条目保持不变。items[].results 始终描述最新的目标版本,而 attempts 会保留较旧的输出。过期的已替换任务 ID 会返回 BATCH_ITEM_VERSION_CHANGED;在进行新的有意返工前,请先重新读取该批次。

    在 Claude 的浏览器连接器中监控批次

    Webhook 会向真实的接收方发送 HTTP 请求。它不会为这个 MCP 连接提供重启空闲 Claude 浏览器对话的方式。绝不要编造回调 URL,也不要承诺在对话结束后还会发送后续聊天消息。

    在用户请求的批处理工作流期间,Claude 应自动监控:

    1. 保留来自 generate_studio_bulk、generate_studio_variants 或 get_studio_batch 的 batch_id 和 state_token。
    2. 调用 wait_studio_batch,传入 batch_id,将 after_state 设为该令牌,并为浏览器连接器使用 wait_seconds: 25。可选分页使用 offset 和 limit(默认 50,最大 100)。
    3. 服务器会在批次发生有意义的变化、完成、暂停、取消或达到有界超时时返回。工作器心跳和即将过期的结果签名不会改变该令牌。响应包含更新后的批次页面、changed、timed_out、stop_reason 和 next_action。
    4. 当 status 为 running 时,继续使用返回的令牌等待,不要要求用户说“再检查一次”。只报告有用的里程碑,不要报告每次无变化的超时。超时不会导致生成失败或取消。不要提交替代批次。
    5. 在 completed 时,报告结果和失败项。在 paused 时,解释 waiting_reason 并等待用户决定。绝不要自动恢复、增加预算或重试付费尝试。cancelled 也会结束此监控循环。

    这会在活动工具工作流中使用服务器端长轮询。如果 Claude 结束其轮次、用户关闭对话,或客户端强制执行运行时限制,批次仍会继续运行,但此连接无法保证会发送新的聊天消息。取消/断开某次等待只会停止观察,不会停止批次。检查或等待不会消耗生成点数。

    wait_seconds 接受 1–240 秒。Claude Code 在较新版本中支持自动将长时间 MCP 调用转入后台;若要等待 240 秒,请将该服务器的 timeout 配置为至少 300000 毫秒,并允许请求通过代理超时。浏览器连接器应使用默认的 25 秒。参见 Claude Code 长工具调用。此行为是客户端特定的,并不保证能唤醒浏览器。

    用于外部接收方的批次 Webhook

    在创建批量批次或变体时传入 callback_url。现有的 API-key webhook 签名密钥以及 X-V4V-Timestamp / X-V4V-Signature 验证规则同样适用。回调目标由幂等创建请求固定;发生网络错误后,请重放相同的 URL 和参数。

    工作器会记录有意义的快照,并投递 batch.updated、batch.completed、batch.paused 和 batch.cancelled。事件包括稳定的 event_id、batch_id、batch_revision、observed_at、state_token、状态、计数和点数总额。result_lookup 指向 get_studio_batch,用于分页文件和任务详情;Webhook 负载不会嵌入会过期的结果 URL。工作器两次 tick 之间的中间状态转换可能会被合并。

    投递使用带租约和有界重试的持久化发件箱。重复投递会使用相同的事件 ID 和负载;签名会在每次尝试时刷新。接收方必须去重并容忍乱序投递,然后在需要时获取当前批次状态。永久性 HTTP 错误会放弃投递;瞬时失败会退避重试。缓慢的 webhook 接收方不会阻塞生成/受理工作器。暂停、取消(含活动工作)以及之后用户请求的重启/返工,都会继续产生更新。投递绝不会开始另一次付费尝试。

    如果只是偶尔手动读取状态,请至少每隔五秒调用一次 get_studio_batch;如果是活跃代理监控,优先使用 wait_studio_batch。单次尝试使用普通的 get_task 工具来获取带签名的下载链接。即使对话或浏览器标签页未保持打开,这些工具也会继续在服务器上处理。

    批量队列只为下一个已受理条目的预估值保留额度。max_credits 会限制已花费点数加上活动保留额度。余额或预算不足会暂停新的启动;在用户提出请求后,调用 control_studio_batch 并传入 action: "resume",还可选择提高 max_credits。暂停/取消会让活动中的尝试完成。已取消的批次不能恢复,但在已受理工作完成后,可以显式重启或返工终态条目。所选条目必须为终态(BATCH_ITEMS_ACTIVE);活动中或提供方请求状态不确定会阻止重试(GENERATION_UNRESOLVED)。NO_FAILED_ITEMS 表示已没有最新失败项。历史、结果和累计花费会在所有操作后保留;计数和条目状态只使用最新的目标版本。新版本共享相同队列和 Credit Log 归因。可选的操作级输入/参数更改会合并到上一次请求之上,而逐条目的返工覆盖项优先。保留的样本门控仍需显式恢复;重启会移除它。有关请求/历史限制和完整示例,请参阅 REST 契约。发生网络错误后请复用相同的 idempotency_key 和参数;绝不要通过创建另一个批次来绕过排队等待。

    生成请求在各账户和应用进程之间最多共享 10 个活动槽位。普通生成具有优先级;批量处理会在管理员定义的全局和每用户限制下使用剩余容量。丢失的提供方响应会继续占用其槽位以便对账,且绝不会触发自动重复的付费请求。API 和 MCP 点数事件会在管理员的 Credit Logs 中分别标记。

    此版本通过 API/MCP 提供生成和单个下载。更大范围计划中的工作室批量界面、CSV 上传、结果审核和 ZIP 导出仍是后续工作。部署后请刷新你的 MCP 连接器工具列表,以发现新的批次工具。字段、预算语义和错误请参见 REST 批量契约。

    26

    视频编辑器#

    位于 /video-editor 的编辑器可让你和你的助手在同一个已保存的多图层时间轴上协作。它支持视频、图片/Logo、源音频、独立的音乐/人声图层、文本、定时字幕、裁剪、分割、速度、音量、淡入淡出以及镜头审阅备注。浏览器提供交互式预览和本地 MP4/WebM 导出。打开视频编辑器进行交互式编辑;工具和限制见下文。

    从 get_editor_guide 开始(也可作为资源 v4v://video-editor 使用)。部署后请刷新连接器的工具列表。

    如需完整的内容工厂,请阅读 get_factory_guide / v4v://factory。create_factory_run、list_factory_runs、get_factory_run 和 submit_factory_stage 会持久保存这九个角色,并支持精确操作重试以及不同的运行/项目修订版本。prepare_factory_review 返回真实采集图像,get_factory_frame 会再次读取它们,而 preview_factory_audio 返回经过测量的 WAV 片段。提交判断前,请检查每一帧采集画面,并审阅运动/语音。repair_factory_run 最多允许两次修正;release_factory_run 会排队,然后验证完整的私有素材库导出、可编辑 ZIP、封面和 REVIEW.md。这些工具要求项目所有权;写入需要 OAuth 读写权限,不需要生成权限,也不会产生点数费用。付费场景生成仍是单独的预算化操作。HTTP 路由、恢复以及测量证据与审核者报告证据的区别,请参见 乌克兰工厂契约。

    工具用途
    get_editor_guide时间轴契约、编辑工作流和空时间轴示例
    get_motion_guide版本化 motion API、实际 schema、原生/HTML 示例、时间/几何单位及生命周期;另见 v4v://motion-api
    get_editor_troubleshooting面向实际错误的版本化恢复指南;另见 v4v://troubleshooting;读取绝不会执行修复或重试
    get_project_transfer_guide本地/V4V ZIP 互操作、二进制请求、权限和恢复;另见 v4v://project-transfer
    export_editor_bundle为当前修订版本的项目准备带作用域的二进制下载请求;执行后获取实际 ZIP
    import_editor_bundle使用 {} 准备二进制 ZIP 上传,然后用 transfer_id 恢复其新项目;不要通过模型文本传输 base64
    get_editor_capabilities实际格式、运行时、本地/共享操作和可选服务
    get_creative_library / search_creative_library发现已安装的共享创意注册表
    get_creative_item单个条目的精确 schema、原始示例、预览路径、许可和限制
    get_style_format_guide仅数据的社区包格式;内容与 v4v://style-format 相同
    create_style_example将新的可编辑风格示例和原始媒体导入账户;不消耗模型点数
    apply_style先用 dry_run=true 预览,再在相同修订版本提交;锁定和手动覆盖仍会保留
    check_editor_project结构/媒体 P0/P1 审核;需分别检查实际帧和音频
    list_editor_projects查找自有/共享编辑器项目,筛选 scope,并读取访问级别
    create_editor_project创建空项目或已验证时间轴
    get_editor_project读取时间轴、修订版本和可续期媒体 URL
    update_editor_project在预期修订版本保存完整时间轴
    edit_editor_project在预期修订版本应用原子化片段/图层/字幕操作
    propose_editor_silence_cuts测量实际源音频,并在不编辑的情况下建议补齐的静音区间;在相同修订版本显式应用已审阅的 remove_time_ranges,以联动所有轨道
    propose_editor_audio_ducking测量实际人声/音乐 stem 和建议的自动化;检查调整前/后的 RMS,然后在相同修订版本显式应用返回的 set_audio_envelope
    get_safe_area_guide版本化编辑输出目标配置和自定义 schema;另见 v4v://safe-areas
    inspect_editor_text使用捆绑字体测量已保存的原生/motion/HTML 文本,并报告采样得到的溢出、重叠和可读性发现
    propose_editor_text_fit在不更改文字、时间或已保存项目的情况下,建议静态文本字号
    propose_editor_scene_layout根据已保存的安全区域配置,建议明确的 motion/HTML 内容边界和最小字号;审阅并应用返回的 set_scene_layout
    list_editor_media按类型和名称搜索自有素材库媒体
    get_editor_media检查自有源素材的时长、尺寸和播放 URL
    preview_editor_project返回最多六张实际合成后的 JPEG 帧供视觉检查
    get_editor_text_styles发现文本/字幕预设、描边、动效和声音反应
    quote_editor_captions在不生成的情况下引用源语音转录
    transcribe_editor_media启动语音转录;会消耗普通账户点数
    get_editor_captions读取转录进度和源时间提示
    append_editor_audio向未锁定图层追加有序音频素材 ID,并可选插入停顿
    export_editor_project排队/恢复 MP4、WebM、MP3 或静态封面 MP4;立即返回 export_id
    get_editor_export轮询状态/阶段,并获取带续新链接的已完成素材库素材
    get_editor_project_sharing所有者:列出协作者并返回私有项目链接
    share_editor_project_with_user所有者:通过邮箱邀请,或更改读/写访问权限,并可选择邮件通知
    remove_editor_project_access所有者:按用户 ID 撤销协作者
    transfer_editor_project_ownership所有者:通过邮箱显式转移给另一个 V4V 账户
    share_editor_project在用户明确要求时,为当前导出视频发布公开链接

    Motion API 与恢复

    从 Kit 0.1.31 开始,get_motion_guide 和 get_editor_troubleshooting 接受 {},并与其 JSON 资源完全匹配。二者都包含 version 和 engineVersion;部署后请发现当前服务器的工具。它们的 V4V OAuth scope 为 v4v:read。读取这些资源不会编辑、渲染、重试或保留点数。

    motion 指南包含实际已注册的 schema、原生和 HTML add_clip 示例、确定性的 prepare / renderAt / dispose 生命周期、本机场景时间和分数几何规则。在新的空项目中,请在已保存的修订版本上应用其示例操作,并预览第 1 秒和第 5 秒。在现有项目中,请有意识地调整轨道/片段 ID 和放置位置。只接受已注册的 JSON 场景;时间轴不会安装任意 HTML 或脚本。验收前请检查实际帧和导出的 motion。

    请结合实际错误代码和已保存状态进行故障排查。出现 CONFLICT 表示需要重新加载并保留并发编辑;媒体缺失时必须提供已获授权的真实来源;字体缺失需要明确恢复。遇到未知响应后,请检查现有导出/镜头尝试。阅读恢复方案并不授权发起新的购买、绕过权限,或重启已取消的操作。

    布局与音频建议的量化分析

    安全区配置文件是带版本的编辑指南,不是平台的官方保证。set_safe_area_profile 会保存该指南,但不会更改渲染后的像素。propose_editor_scene_layout 会使用它来提出明确的 motion.layout;请查看 applicable 和报告,然后通过 edit_editor_project 在相同修订版本上应用其返回的操作。layout:null 会撤销该设置。之后更改指南不会让内容重新适配。inspect_editor_text 会采样真实字形/DOM 框;但媒体中烘焙的文字、旋转裁切、视频上的对比度、完整运动效果和听感仍需人工审查。

    如需为人声下方配乐,请使用实际的 project_id、revision、互不重叠的 voice_clip_ids 和 music_clip_ids 调用 propose_editor_audio_ducking,并可选提供 options。默认目标是将人声/音乐 RMS 余量设为 12 dB,在 −40 dBFS 检测活动,并将衰减限制为 30 dB。服务会按所选来源的实际修剪、速度、音量和淡入淡出进行混音;同时也会对建议的音乐重新混音并测量。请检查基线 comparison、测得的 after、targetMet、警告和短语区间,试听后,再通过 edit_editor_project 在相同修订版本上明确应用其返回的 operations。

    所选音乐自动化会被替换,而不是叠加;基础增益/淡化仍会保留。曲线可随 ZIP 携带,并跟随其音乐片段。更改人声时间/电平、来源或音乐位置后,需要重新计算。最多支持 500 个人声片段和 20 个音乐片段、每个 V4V 来源 100 MiB、总计 512 MiB,以及每个分析窗口 64 个相交片段;资源/速率限制同样适用。读取权限允许提出建议,而应用建议需要写入权限。测量和本地编辑都不会消耗点数。RMS 和检测到的振幅并不能证明可懂度;静音切点建议同样需要先试听,再进行全轨道联动编辑。

    通过 V4V MCP 传输便携 ZIP

    读取 get_project_transfer_guide / v4v://project-transfer。两个主机都使用相同的 .v4v.zip 内容:带版本的 bundle.json 和原始 assets/<sha256> 字节。只有本地 Kit 接受 directory 参数;V4V 会明确拒绝本地文件系统路径。

    导出:使用 project_id 和当前 revision 调用 export_editor_bundle,然后使用完全精确的作用域请求头执行其 download_request,并保存实际的二进制响应。该工具只是准备好了一个请求,尚未创建文件。下载时会重新检查账户/key/OAuth、项目/媒体访问权限和修订版本。其响应包含 X-Content-SHA256;请比对下载到的字节。如果项目已变更,请再次读取其修订版本,并有意识地请求另一次导出。

    导入:使用 {} 调用 import_editor_bundle,使用返回的 upload_request 以 POST 提交原始 ZIP 字节(application/zip,不是 multipart),然后使用其 transfer_id 调用 import_editor_bundle。这会创建一个新项目,验证/探测来源,并重映射嵌套素材 ID。确认信息丢失后,请恢复同一传输:已完成的导入会返回现有项目。中断的导入可使用原始字节重新获取其已过期租约;不同文件则需要新的传输。绝不要虚构文件数据,也不要把大量 base64 打印到模型上下文中。无法访问二进制文件的客户端可使用工作室 打开项目 ZIP。

    传输凭据会在 15 分钟后过期;回执可在七天内恢复。令牌应放在返回的请求头中,而不是 URL、时间线或公开消息中。导入需要 OAuth 读 + 写;导出需要读取权限和当前项目访问权限。ZIP 及其解压后的内容限制为 100 MiB;每个进程最多两个传输,且受请求体大小、租约以及按用户/请求计的速率限制约束。导入/导出不会执行生成、公开分享或通知。账户共享权限和模型凭据不会随 ZIP 一起传输。交付前,请重新打开返回的项目并检查实际媒体/帧。

    通过 MCP 进行私有项目共享

    助手可以在不要求用户操作浏览器的情况下完成私有共享。如果缺少收件人的 V4V 邮箱或读/写访问级别,请先询问,然后调用:

    json
    {
      "name": "share_editor_project_with_user",
      "arguments": {
        "project_id": "169000000000000000000002",
        "email": "collaborator@example.com",
        "access": "write",
        "notify_by_email": true
      }
    }

    仅当用户要求发送邮件通知时才使用 notify_by_email: true;其默认值为 false。返回 project_link 供用户发送,并准确报告 emailNotification:failed 表示访问权限已授予,但邮件未发送。项目链接需要受邀账户访问;已登出的收件人登录后会返回同一项目。无需视频导出、生成或生成点数。

    get_editor_project_sharing 会列出协作者及其 userId、邮箱和访问权限。使用 share_editor_project_with_user 更改权限;使用 remove_editor_project_access 及其 user_id 撤销已列出用户。只有在用户明确要求转移所有权并提供新所有者邮箱时,才可转移。旧所有者将失去访问权限;其他协作者和来源引用会保留。所有管理调用都会强制要求项目所有权;OAuth 变更还额外要求 v4v:write。

    share_editor_project 仍然是另一种操作:它会将已完成导出的成片视频发布到公开分享页面。不要把它用于私有协作者邀请。部署后请刷新/重新连接 MCP 连接器,以发现新工具和说明。

    编辑器项目 ID 与工作室/实验室生成项目 ID 是分开的。请使用 list_editor_projects,不要使用 list_projects,来发现它们。生成仍可通过现有的模型发现、估算和 generate_lab 工具使用。已完成媒体的 file_id 可直接用作时间线 assetId。语音转文本也可发现为 type: "subtitle";优先使用 ai.gemini_3_5_transcribe(Gemini 3.5 Transcribe)。其已完成 API 任务结果包含文本、SRT、VTT,以及以源秒为单位计时的 cues/words。专用编辑器转录工具可简化对现有素材库来源的使用。

    一个典型的代理请求:

    用我素材库中的片段制作一支 20 秒的竖版短片。检查有代表性的帧,并在展示成本后,用新生成的内容替换失真的镜头。修剪镜头,添加我的标志、轻柔的背景音乐、旁白和带时间点的字幕。将完成的视频保存到素材库,并给我一个下载链接。

    助手应当:

    1. 阅读指南,找到项目和源媒体,并检查时长与播放情况。
    2. 使用当前修订版本创建或编辑时间线。将标志作为图像添加到上方视觉图层,将人声/音乐添加到音频图层。原始媒体不会被更改。
    3. 使用 preview_editor_project 检查所选帧时间。设置片段 review: "keep" 或 "replace",并在 note 中记录原因。帧并不能证明运动或声音质量;也要检查源媒体播放。
    4. 发现/估算所请求的模型,使用唯一幂等键生成替换内容,并等待其完成后的文件 ID。替换所选片段的来源,并将其修剪/时长限制到新来源范围内。
    5. 引述/转录原始人声来源,轮询间隔至少五秒,然后使用 sourceClipId 添加提示项,以适配修剪和速度。检查转录文本。提供现有的带时间点提示项不会消耗点数。
    6. 使用 export_editor_project 提交当前修订版本;在排队/渲染期间,以至少五秒间隔轮询 get_editor_export。已断开的 MCP 请求不会取消作业。只有 completed 且同时带有素材 ID 和下载 URL 才表示成功;在用 retry_failed: true 明确重试前,请先检查失败原因。仅在用户要求时创建分享链接。

    在 get_editor_project 之后进行的定向编辑示例:

    json
    {
      "project_id": "PROJECT_ID_FROM_CREATE",
      "revision": 3,
      "operations": [
        {
          "type": "update_clip",
          "clipId": "shot-1",
          "changes": {
            "trimStart": 1.5,
            "duration": 3,
            "volume": 0.25,
            "review": "keep"
          }
        },
        {
          "type": "split_clip",
          "clipId": "shot-2",
          "time": 7,
          "newClipId": "shot-2b"
        },
        {
          "type": "add_captions",
          "sourceClipId": "voice-1",
          "cues": [
            {
              "start": 0.2,
              "end": 2.1,
              "text": "A new perspective."
            }
          ]
        }
      ]
    }

    start/duration 使用时间线秒,trimStart 使用源秒,而分割点 time 是绝对时间线时间。修剪前请读取实际媒体时长。add_clip 接受一个带有唯一 id、trackId、kind、assetId、start 和 duration 的片段;其他字段有默认值。文本使用 kind: "text" 和 text,而不是素材。轨道类型为 visual、audio 或 text。add_track、update_track、remove_track 和 reorder_tracks 用于管理图层。轨道按数组顺序渲染,最后一个位于最上层。通过重叠视觉图层并使用淡化来实现叠化。

    服务器会拒绝无法访问的媒体、媒体类型不匹配、无效修剪和过期修订版本。遇到修订冲突时,请读取新版本并重新应用预期更改。不要覆盖其他编辑者的工作。已打开且未本地修改的浏览器编辑器会自动获取代理更改;本地已修改的草稿会保留其更改并显示冲突。

    代理帧检查和视觉时间线 WebM 导出要求部署环境中提供 Playwright Chromium。这些视觉时间线导出最多支持两分钟和 300 MB 源媒体,并返回已保存的 WebM;重复导出相同修订版本会复用其现有素材。浏览器导出支持十分钟时间线,并在设备具有 H.264/AAC 编码器时提供 MP4。如果渲染失败,请报告错误和编辑器链接;不要声称导出成功。时间线编辑/渲染不会消耗模型点数;生成/转录会消耗。分享会创建一个任何持有链接的人都可见的链接。

    27

    Gemini text-to-voice#

    先使用 type="audio" 调用 list_models,然后为 ai.gemini_3_8_flash_tts 或 ai.gemini_3_8_flash_lite_tts 调用 get_model。 二者都会从最多 10,000 个口述字符生成单说话人 WAV 音频:

    json
    {
      "model": "ai.gemini_3_8_flash_tts",
      "input": {
        "text": "Welcome! <short pause> Let’s get started."
      },
      "parameters": {
        "voice": "Kore",
        "style": "Warm and friendly"
      },
      "idempotency_key": "unique-intentional-generation-id"
    }

    Read get_model.voices for each preset’s exact id, gender, description and free preview_url. Send the selected ID as parameters.voice; omit metadata and preview URLs from generation arguments. Check the balance and call estimate_generation with source="lab" first, then call generate_lab. Read get_task for owned audio file IDs and signed download links. Delivery instructions belong in style; they are not spoken. Flash focuses on expressive narration, Flash-Lite on efficient generation. Provider selection is managed in admin settings, not through an MCP parameter. ElevenLabs text-to-voice is temporarily disabled.

    28

    样式化文本、字幕与 Google 转录#

    get_editor_text_styles 会返回 14 种字幕预设、6 种标题预设,以及一个 fontCatalog,其中包含 12 款内置字体和 4 个旧版系统别名。每个字幕预设都会对真实的词级时间戳作出响应。使用预设 category 和 use 选择处理方式:word-pop(创作者冲击感)、caption-marker(青柠标记)、caption-underline、editorial(播客面板)、caption-soft、caption-outline 或 neon-pulse(霓虹辉光),以及其他词语动效样式。标题有各自的预设:title-clean、title-condensed、title-magazine、title-tech、title-sticker 和 cinema-gold。新字幕默认使用 100 px 的全大写 Montserrat,每个短语三个词。请保持统一的字幕风格与互补的标题风格、足够强的对比度和安全边距。现有已保存时间线会保留其设置,直到重新设定样式。参见完整字体排印目录。

    优先使用内置 fontFamily ID:inter、montserrat、manrope、oswald、rubik、roboto-condensed、unbounded、nunito、playfair-display、roboto-slab、jetbrains-mono、comfortaa。它们支持拉丁字母和乌克兰西里尔字母,并会在预览和两种导出路径渲染前从 V4V 加载。fontCatalog.weights 会给出每个字体家族支持的范围。旧版 sans、impact、serif 和 mono 依赖系统字体。绝不要忽略字体加载错误并声称导出成功。

    文本片段支持 strokeWidth(0–24 输出像素)、strokeColor、color、fontFamily(目录 ID)、fontWeight(400/500/600/700/800/900,会限制到该字体支持的范围内)、textBackground、backgroundColor、backgroundOpacity、accentColor、textAnimation、activeWordEffect(none、color、pop、shake、swing、spin、box、underline、glow)、activeWordColor(标记前景色)、letterSpacing(-0.06–0.2 em)、lineHeight(0.9–1.8)、textShadow、shadowColor、shadowBlur、shadowOffsetY、backgroundFit(box 或 text)、backgroundRadius、textTransform(none、uppercase)、fontSize、animationIntensity(0–1)、audioReactive 以及可选的 audioSourceClipId。动画包括 none、fade、slide、pop、float、shake、pulse、color-cycle 和 karaoke。audioReactive: true 使用实际音频音量,包括修剪、速度、淡入淡出、音量以及静音/隐藏轨道。除非提供了源片段 ID,否则它会跟随所有可听来源;它不会检测音乐节拍。预览、拖动定位、本地导出和服务器导出共用此渲染器。

    使用带有 { "type": "apply_text_style", "clipIds": ["caption-1", "caption-2"], "stylePreset": "creator-pop" } 的 edit_editor_project 为多个字幕设置样式。使用 update_clip 进行微调。add_captions 接受 stylePreset、maxWordsPerCaption(1–8,默认 3)以及提示项 words,例如 { "text": "Hello", "start": 1.2, "end": 1.6 }。提示词使用源秒,sourceClipId 会将它们与源修剪、速度和时间线位置对齐。在单个文本片段上,wordTimings 使用相对于该片段的秒数。口语词效只会高亮并动画化该时刻实际说出的词;请保留真实时间戳。转为大写只会更改渲染,不会重写原始文本或时间。SRT 只提供提示项时间,因此绝不要据此虚构词级时间。

    如需转录,请先使用 type: "subtitle" 调用 list_models,然后使用 model: "ai.gemini_3_5_transcribe" 调用 get_model。使用 estimate_generation 报价,并通过 generate_lab 提交同一请求:

    json
    {
      "model": "ai.gemini_3_5_transcribe",
      "input": {
        "audioUrl": {
          "file_id": "OWNED_AUDIO_ID"
        }
      },
      "parameters": {
        "language_code": "auto",
        "diarize": false
      },
      "idempotency_key": "transcribe-unique-request"
    }

    或者,向 videoUrl 提供一个归你所有的视频引用。只能精确选择一个来源,最长 15 分钟。已连接的 Google 服务账号会处理身份验证。不要提供服务商凭据或路由参数。使用带有 type: "subtitle" 的 get_task 轮询 results;请保留其提示项和词级时间,用于编辑器字幕。Google 目前将词级时间戳标记为实验性功能,因此请检查转录准确性。编辑器的报价/转录工具现在默认使用此模型。旧版 ai.speech_to_text 仍然独立存在;管理员可以单独隐藏它。失败的付费请求会按照正常作业生命周期退款,且不得自动作为新的购买重试。

    完成编辑器字幕工作流

    转录文件不会将字幕插入到编辑器项目中。对于现有影片:

    1. 读取 get_editor_project,识别源片段及其 assetId。
    2. 如果你已经为该源片段取得成功的 generate_lab / get_task 字幕结果,请复用其中的 cues,并直接跳到第 4 步进行插入;无需进行视频 file_id 或第二次转录。否则,先调用 quote_editor_captions,再使用该 asset_id、language: "auto"(或 BCP-47 代码)和唯一的 idempotency_key 调用 transcribe_editor_media。网络超时后请复用该 key。
    3. 轮询 get_editor_captions,每次间隔至少五秒。若出现 failed,请报告 error 并停止。新的付费尝试必须由用户提出请求。
    4. 当返回 succeeded 时,要求 cues 非空,获取最新项目修订版本,并将这些精确的字幕条目传给 edit_editor_project,同时附上 type: "add_captions"、源片段的 sourceClipId、stylePreset: "word-pop" 和 maxWordsPerCaption: 3(或其他请求的词语预设)。
    5. 在已保存的时间线中验证新的文本片段,并在实际字幕出现时间进行预览。检查文字准确性。如果源内容在转录期间发生变化,或裁剪后没有重叠语音,必须如实报告;不要声称插入成功。复用已完成的字幕条目来解决编辑冲突,无需再次生成。

    保留所有返回的词级时间戳,包括短词起止偏移相同的情况。使用 update_clip / changes.name 重命名叠加层;使用 changes.text 修改可见文字。使用 update_track / changes.name 重命名其图层。保留 ID,并遵守锁定图层限制。

    Gemini 转录每次请求至少花费 1 点数,包括短片段;生成前请先报出当前按时长计费的价格。字幕 JSON 包含 time_unit: "seconds"、扁平的 words 数组和 cues[].words,其中每个词都包含 text、start、end 和可选的 speaker_id。这些词可用于卡拉 OK 和其他同步样式。SRT 仅包含行级时间。实验室可预览定时词语,并复制/下载 JSON 或 SRT。视频编辑器可通过“字幕 → 导入 SRT 或 JSON”直接接收该 JSON;请选择一个大型口播预设,并使用“片段属性 → 词语与时间”修正单个词,而不移除其时间信息。MCP 更正时应同时传入 changes.text 和完整的已更正文案 changes.wordTimings;仅改文字会清除过期的时间信息。

    要在不再次生成的情况下缩短现有的定时字幕图层,请使用:

    json
    {
      "project_id": "EDITOR_PROJECT_ID",
      "revision": 3,
      "operations": [
        {
          "type": "reflow_captions",
          "trackId": "CAPTION_TRACK_ID",
          "maxWordsPerCaption": 3
        }
      ]
    }

    请使用实际的当前修订版本和图层 ID。这样可以保留真实的词语时间、样式和图层,并返回包含新片段 ID 的更新时间线。对这些 ID 使用 apply_text_style 应用共享词语预设。在浏览器中,使用“片段属性 → 词语与时间 → 每条字幕的词数 → 将此图层拆分为短字幕”,然后在“文字与外观 → 样式 → 将样式应用到图层”中操作。没有转录时,无法将 SRT 行准确拆分为带定时的词语。

    有声书:组装配音、设置标签、导出带封面的 MP3 或 MP4

    MCP 1.15.0 新增了与视频编辑器中相同的 音频与有声书 工作流。读取 get_editor_guide 获取 audiobookTimeline,或在编辑前读取当前项目。对于最长 7,200 秒(两小时)、1,000 个片段和 24 个图层 的时间线,将 timeline.mode 设置为 audiobook。视频模式仍保留十分钟/500 个片段的限制。

    1. 通过 list_editor_media / get_editor_media 查找现有录音,或上传/导入它们。仅在用户提出请求时生成新的语音,并使用模型发现、点数估算和现有 Gemini TTS 工具。编辑器负责组装录音;不会猜测每一行对应的说话人。
    2. 按需为每位旁白、对话、音乐或音效添加一个音频图层。使用 append_editor_audio,并传入有序的 asset_ids、track_id、当前 revision 以及可选的 gap_seconds(0–60)。它会将完整片段追加到该图层,不会产生按帧取整的间隙。它绝不会对文件名排序,也不会截断最后一部分来适配。若需要重叠或自定义时间,请使用现有片段操作。裁剪、速度、音量、淡入淡出、静音和隐藏图层都会影响混音;更改速度会改变音高。
    3. 通过 edit_editor_project 保存标签、比特率和封面,例如:
    json
    {
      "project_id": "<project ID>",
      "revision": 3,
      "operations": [
        {
          "type": "set_audio_settings",
          "mode": "audiobook",
          "settings": {
            "metadata": {
              "title": "Розділ перший",
              "artist": "Олена та Андрій",
              "album": "Книга пригод",
              "albumArtist": "Назва видавництва",
              "composer": "Ім’я автора",
              "year": "2026",
              "track": "1/12",
              "genre": "Audiobook",
              "comment": "",
              "copyright": ""
            },
            "coverAssetId": "<accessible image asset ID>",
            "bitrateKbps": 128
          }
        }
      ]
    }

    settings 会替换已保存的音频设置:请保留用户未要求更改的字段。所有标签都是字符串。artist 记录旁白/表演者,composer 可记录作者,album 标识书籍,year 为四位数字,track 为数字或“数字/总数”。不要虚构制作人员或版权信息。标题为空时将回退为项目标题。MP3 包含 ID3v2.3 Unicode 标签,并且在选择时包含封面 APIC 图片。该图片会嵌入文件中,而不是通过 URL 引用。MP3 可不带封面;带封面的 MP4 则必须有封面。比特率可选 96、128(默认)、192、256 或 320 kbps。

    1. 使用已保存的修订版本以及 format: "mp3" 或 format: "mp4-cover" 提交 export_editor_project。如果两种文件都需要,请同时请求两者。每个项目/修订版本/格式都有自己持久存在的任务,因此一种格式绝不会替代另一种。轮询 get_editor_export,每次间隔至少五秒,直到出现 completed 或 failed。阶段包括加载媒体、带进度的音频混音、编码和保存。客户端断开连接不会取消任务;重复提交可恢复任务。失败的任务需要显式的 retry_failed: true。
    2. 确认 status: "completed"、assetId 以及已签名的下载/播放链接。在报告完成前,请检查最终混音、时长、请求的标签和图片。MP3 会保存为素材库中的音频素材;带封面的 MP4 会保存为视频素材。仅检查画面帧无法验证音频或元数据。公开视频分享工具不适用于 MP3 文件;私有项目协作仍然可用。

    mp4-cover 格式会在整个音频时长内,在项目背景上显示一张适配后的封面。时间线中的可视片段、文字和字幕不会包含在此格式中。若要渲染这些内容,请使用现有的 format: "webm" MCP 导出(默认,最长两分钟)或浏览器 MP4/WebM 导出(最长十分钟)。

    音频导出仅限所有者使用,不消耗生成点数,并且需要持久化编辑器工作进程以及带有 libmp3lame 和 libx264 的 FFmpeg/ffprobe。这两种格式都不需要 Chromium。限制如下:源文件总计 1 GB、每个导出文件 300 MB、每 30 秒混音窗口最多 64 个音频片段分段。对于更大的书籍,请降低比特率或拆分成多个部分。设置和封面引用会保存在时间线中,受修订版本检查约束,并会在共享或所有权转移后遵循项目的媒体权限。本次发布不包含章节标记、声音克隆或自动说话人分配。

    共享样式库与样式包

    /video-editor/gallery 和设计面板显示与本地 Kit 相同的 30 个原生样式包。每个样式包都包含五个可编辑场景、一个 12 秒的静音预览、原始带标签插画、提示词、评分规则和哈希清单。这是可复用的场景系列演示,不是事实性产品宣传。来自 get_creative_item 的预览路径相对于 /api/video-editor/creative-assets/;其中仅包含随附的原创材料,绝不包含账户媒体。

    create_style_example 会将真实的源图片导入已登录所有者的素材库,并重新映射时间线的媒体 ID。它使用 v4v:write,不消耗生成点数。apply_style(dry_run=true) 还要求具备编辑权限和当前修订版本,会报告已更改/已锁定/不受支持的片段,并且不会写入。查看方案后,请用相同参数和修订版本进行应用。所选场景范围会更改这些场景的入场转场;片段时间和音频保持不变。

    有限的Open Video Kit生成预算

    create_generation_budget 创建一个不扣费的不可变共享上限;get_generation_budget 读取实际消耗和预留量,close_generation_budget 永久关闭新配额申请。对于受支持的媒体,estimate_generation 返回一个有效期五分钟的已签名 quote_token。在当前 generate_lab / generate_studio 中同时传入 budget_id、max_credits 和 quote_token;idempotency_key 为必填项。已接受请求的完全重复提交不会触发二次生成。并行预留在服务器端统一计算;按令牌计费的对话不在此路径范围内。预算并非用户独立授权消耗点数的凭证。详细合同与验证规则:Cloud Kit。

    私有参考样式(Open Video Kit 0.1.24)

    get_reference_guide / v4v://reference-style 记录共享工作流。analyze_reference_style 接受稳定的 reference_id、归自己所有的素材库素材(source: { type: "asset", assetId })或明确公开的 video|image|page URL。它会返回测量得到的调色板、初步边界/节奏以及实际帧时间;get_reference_frame 返回 PNG 内容。在执行 review_reference_style 前,请检查所有记录的帧;该操作要求提供原创字体排版/布局/运动/转场/节奏规则、完整 tokens、审核者限制以及时间/SHA-256 引用。get_reference_profile 返回私有的可移植 JSON。apply_reference_style 默认为试运行;提交需要当前归自己所有项目的修订版本,包括修订版本零。参考视频绝不会嵌入蒙太奇或 ZIP 中。

    读取工具要求 v4v:read;分析/审核/应用要求 v4v:read 和 v4v:write。它们既不要求 v4v:generate,也不消耗生成点数。V4V 参考/工厂证据文件使用逐对象密钥加密,而这些密钥仅保留在所有者范围的数据库清单中,私有文件会被阻止通过通用素材投递访问。访问时会检查原始参考素材库的所有权。参见乌克兰语实现与限制。

    几何片段蒙版与分层视差

    Kit 0.1.32 adds clipMasks and layeredParallax capability flags. Search kind=effect for mask-circle, mask-ellipse, or mask-rounded-rect, then read get_creative_item for the actual schema and limits. Apply set_mask through edit_editor_project at the saved revision with write access; mask:null clears it. The mask's x/y/width/height are clip-relative fractions and its bounds must remain inside the clip box. It follows rotation/scale/keyframes, clips after effects and before transitions, and does not change audio. Locked layers and audio-only targets reject the operation.

    get_motion_guide.schemas.mask 和 recipes.parallax 与本地工作室共享。后者通过普通位置关键帧提供可编辑的双层运动。请预览实际帧;这不是自动深度估计。共享 GUI 控件位于“设计 → 效果”。ZIP 会保留蒙版;文字检查返回 TEXT_MASK_REVIEW,因为边界检查无法保证弯曲蒙版内的可读性。请参见共享双语约定。

    29

    创意合集与代理规划#

    “设计 → 素材库”提供 28 个可编辑的原生合成,包括拼贴、连续镜头运动、弹簧面板、手绘角色、字幕、产品演示和发布序列。Kit 0.3.7 还包括十种原创样式、五种光栅效果和十五种转场。其中十三种着色器转场需要 WebGL,输出最长边最高 4096 像素。

    请使用 get_reviewed_library_guide(资源 v4v://reviewed-libraries)查看精确 schema、源许可证和限制。search_library_references 和 get_library_reference 提供 456 条参考元数据项;这些不是已安装的可执行模板。plan_library_scene 为只读,并返回针对当前修订版本中 edit_editor_project 的操作。请使用归自己所有的素材库媒体或已注册的本地项目媒体;原始本地字节始终保留在用户设备上。编辑后请检查实际渲染帧。

    使用 AI 规划 会保存项目并准备一个可编辑的视频工厂请求。它不会提交命令、消耗点数、上传原始文件或授权生成。代理会在编辑前澄清会产生实质影响的缺失创意选择。原生渲染不需要生成服务;可选的付费操作会保留现有报价并要求明确批准。不会启用上游安装程序、任意 HTML/JavaScript、可执行音乐或本地历史读取器。源/许可证审查和原创等效项随版本化 Kit 文档一同提供。

    蒙太奇质量与证据

    读取 get_montage_quality_guide / v4v://montage-quality 了解共享的品味规则和诚实证据限制。plan_montage_beats 从真实词语时间中推导帧对齐的视觉切点;plan_compact_captions 会将 1–3 个词分组,而不虚构时间戳。analyze_ui_regions 测量归自己所有的截图边界;rectify_ui_region 会根据返回的指纹/区域 ID 创建单独的透视校正图像。detect_media_scenes 测量源窗口中最长 600 秒的视觉切点。这些操作会保留源内容,不会生成付费媒体。

    compare_narration_transcript 要求对精确的 audio_asset_id 进行一次已完成且归自己所有的转录 run_id;它会将实际转录与 script 和可选的已确认姓名进行比对。ASR 文本无法确定发音重音或自然表达。购买转录或补录只能通过常规的报价授权流程进行。

    preview_editor_project 最多接受 12 个实际帧 times;contact_sheet: true 会返回一张图像供审核。工厂浏览器模式会在用户设备上执行检查/校正,并将原始文件保留在本地。对于仅有浏览器原始文件的外部 MCP 调用方,会收到 BROWSER_REQUIRED;此类浏览器操作请使用开放式 Factory 代理。新的 Factory 命令会针对八个明确的证据问题分别记录内容审核答案和完成审核答案。未知证据不算通过审核。

    失败的 get_task 结果包含 error.provider_error、经过清理的模型 服务原因以及 error.provider: "managed"。已知失败包括 hint 和 retryable;临时性的限流/超时还会提供 retry_after_seconds: 60。在更改请求或要求进行另一次付费尝试之前,请先阅读原因。未知错误会保留其经过清理的原因,不会假定重试一定有效。REST 任务响应和已签名的 task.failed 回调使用相同字段;参见生成失败诊断。