doc2video

d2v — doc2video CLI 和 MCP 服务

将文档和照片所在的文件夹交给 d2v，它就会在 doc2video.io 上制作带旁白的 AI 视频。你可以自己操作，也可以让 Claude 或 ChatGPT (Codex) 替你操作——既可以通过 CLI，也可以将其用作 MCP 服务。

d2v create "Spring Open House" ./open-house --duration 1m --aspect 9:16 \
  --direction "Warm and inviting, finish on the garden" --build --wait

安装

需要 Node.js 18.18+。

npm install -g doc2video     # installs the `d2v` (and `doc2video`) command

也可以无需安装直接运行：npx doc2video <command>。

登录

d2v login

浏览器会打开 doc2video。登录（或注册），确认代码与终端中的代码一致，然后点击 Approve——就完成了。密钥会保存到 ~/.doc2video/config.json，并显示在控制面板的 API 页面中，你可以在那里撤销密钥。如果这台机器上没有浏览器，运行 d2v login --no-browser 会打印可在任意位置打开的链接。

Agent 需要分两步操作，这样才能向你显示链接：运行 d2v login --start --json（返回链接和代码），然后在批准后运行 d2v login --wait。通过 MCP 时，d2v_connect_account 工具也会执行相同操作。

你也可以粘贴在 API 页面创建的密钥（d2v login --key d2v_…），或设置 DOC2VIDEO_API_KEY。若要连接其他服务（例如本地开发环境），请使用 --url http://localhost:3000 或 DOC2VIDEO_URL。

文件夹中可以放什么

类型	格式	用途
文档	PDF、DOCX、PPTX、Markdown、TXT、CSV、JSON	故事：脚本根据这些内容撰写
照片	JPG、PNG、WebP、HEIC（iPhone）	展示给脚本撰写者，并在场景中呈现

会递归扫描文件夹（跳过隐藏文件）。旧版 .doc/.ppt/Keynote/Pages 文件会被跳过，并提示你进行转换。只包含照片的文件夹也可以使用——故事会根据照片和你的创作方向构建。如果文件夹中没有任何文件，请使用 --draft "description"。

默认情况下，照片会原样使用——裁剪为视频画幅，可免费用于静态场景或 Ken Burns 场景（你只需为 AI 工作付费，例如根据照片生成 AI 视频片段）。使用 --photos restyle 可让 AI 将照片润饰为电影感关键帧，同时保留真实主体；也可以通过 d2v scene <p> <n> --photo-treatment restyle 为单个场景设置。

工作流

d2v create "Name" ./folder [settings] --build --wait   # storyboard: script → keyframes → narration → preview
d2v show <project>                                     # scenes, narration, preview URL, next steps
d2v pull <project>                                     # keyframes + storyboard.md to a local folder

# steer, scene by scene
d2v keyframe  <p> 3 "warmer light, show the sign"      # edit the image
d2v keyframe  <p> 3 --fresh                            # brand-new image
d2v narration <p> 3 --prompt "shorter and punchier"    # AI rewrite + new voice-over
d2v narration <p> 3 --text "Exact words."              # exact text + new voice-over
d2v scene     <p> 3 --engine veo3                      # still | kenburns | runway | veo3
d2v scene     <p> 3 --photo IMG_2041.jpg               # feature a photo (or --photo none)
d2v run       <p> preview --wait                       # refresh the preview video

# finish (costs money — you pay in the browser)
d2v estimate <p>
d2v buy <p> --open          # or: d2v buy <p> --credits, or: d2v redeem <p> CODE
d2v produce <p> --wait      # AI clips → final assembly
d2v download <p>

免费故事板和积分

每天可获得 2 个免费故事板，未付费项目还可重做场景 20 次。之后，每个故事板需花费 $0.50 预付积分——向 create --build、build 或 run 传入 --use-credits 即可确认（不传入时，命令会停止并告知价格）。积分也可用于解锁成片：d2v buy <p> --credits。

d2v credits                 # balance, free storyboards left today, recent activity
d2v credits add 10 --open   # top up $5, $10 or $25 in the browser

项目可以通过 ID、8 位 ID 前缀或准确名称指定。d2v help <command> 会显示所有选项；d2v guide 会打印完整的工作流指南。

设置（用于 create 和 set）：--duration auto|30s|1m|2m|5m|10m、--aspect 9:16|16:9、--direction、--voice（参见 d2v voices）、--stability、--photos original|restyle、--consistency/--no-consistency、--client、--email、--phone、--website。

长时间运行的步骤

所有任务都在 doc2video 的服务端运行；生成故事板需要几分钟，最终制作耗时更长。--wait 会阻塞命令并在 stderr 中显示进度，Ctrl+C 只会停止等待——任务会继续运行。之后可通过 d2v wait <project> 继续查看。步骤可以在服务端串联执行，因此即使终端关闭，build 也会继续运行。

脚本和 Agent

在任何命令后添加 --json，即可在 stdout 上输出机器可读内容（进度信息仍输出到 stderr）。 退出代码：0 成功，1 错误，2 用法错误，3 需要付费，4 --wait 超时， 5 达到速率限制或每日免费额度上限。

在 Claude 或 ChatGPT 中使用

托管 MCP 服务（无需安装）

doc2video 也会为你运行 MCP 服务，地址为 https://doc2video.io/mcp。将其添加为自定义连接器，并在提示时使用你的 doc2video 账户登录（OAuth — 无需复制密钥）：

• Claude（claude.ai、Desktop、移动端）：Settings → Connectors → Add custom connector，URL https://doc2video.io/mcp。
• Claude Code： claude mcp add --transport http doc2video https://doc2video.io/mcp，然后运行 /mcp 登录。
• ChatGPT： 添加服务器 URL 为 https://doc2video.io/mcp 的连接器（开发者模式），并使用 OAuth 登录。
• Cursor、VS Code 和其他客户端： 添加类似 { "doc2video": { "url": "https://doc2video.io/mcp" } } 的远程服务条目（VS Code："type": "http"）。

托管服务提供相同的工具，但无法访问你电脑上的文件：请向其提供文本、公开链接（PDF、Word 和 PowerPoint 文件、照片、网页），或在它链接到的项目页面上添加文件。若要处理本地文件夹，请使用下方的 CLI 或 d2v mcp。你可以在控制面板的 API 页面查看已连接的应用，也可以断开连接。

Claude Code / Codex CLI（Shell）

两者都可以直接运行 d2v。在包含文件的文件夹中打开终端 Agent，并提出请求，例如 “用 doc2video 根据这个文件夹制作一段 60 秒的竖屏视频，给我看分镜脚本，并加强开场效果。” 若要获得更好的效果，请安装 Agent 指令：

• Claude Code： 将 agents/SKILL.md 复制到 ~/.claude/skills/doc2video-cli/SKILL.md
• Codex CLI： 将 agents/AGENTS.md 追加到 ~/.codex/AGENTS.md（或该文件夹的 AGENTS.md）

这两个文件都随软件包一起提供 — 可在 $(npm root -g)/doc2video/agents/ 下找到。

MCP（Claude Desktop、Claude Code、Codex、任何 MCP 客户端）

d2v mcp 会通过 stdio 运行 MCP 服务，提供涵盖整个工作流的工具 — 包括 d2v_view_storyboard，它会返回关键帧图像，让模型能够实际查看分镜脚本并提供视觉反馈。它已以 io.github.doc2video/d2v 的名称列入官方 MCP Registry。

下面的 API 密钥为可选项：不提供密钥时，d2v_connect_account 工具会提供一个链接，让你在浏览器中登录（或注册），并记住该密钥。

Cursor / VS Code — 使用本页顶部的按钮。

Claude Code

claude mcp add doc2video -- npx -y doc2video mcp
# or with a key from doc2video.io/dashboard/api-keys:
claude mcp add doc2video -e DOC2VIDEO_API_KEY=d2v_xxx -- npx -y doc2video mcp

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "doc2video": {
      "command": "npx",
      "args": ["-y", "doc2video", "mcp"],
      "env": { "DOC2VIDEO_API_KEY": "d2v_xxx" }
    }
  }
}

Codex CLI — ~/.codex/config.toml：

[mcp_servers.doc2video]
command = "npx"
args = ["-y", "doc2video", "mcp"]
env = { DOC2VIDEO_API_KEY = "d2v_xxx" }

全局安装后，你可以使用 "command": "d2v", "args": ["mcp"]，而不是 npx。

ChatGPT（Web/桌面端）： ChatGPT 仅连接远程 MCP 服务，因此请使用上方的托管服务。 处理本地文件夹请使用 Codex CLI。

REST API

CLI 是 doc2video REST API 的轻量客户端 — 请参阅 API.md 了解如何直接调用。

开发

npm install
npm run build      # compile to dist/
npm test           # build + end-to-end tests against a mock API (no network)
npm link           # use your local build as `d2v`

推送 v* 标签时，GitHub Actions 会发布新版本到 npm（附带来源证明）和 MCP Registry。欢迎在 github.com/doc2video/cli 提交问题和拉取请求。

许可证

CLI 和 MCP 服务采用 MIT 许可证。它们是托管版 doc2video 服务的客户端，服务地址为 doc2video.io，并有其自己的 条款。