开发者文档

PromptVV API 与 MCP

从创建密钥到取得分析结果，本文档覆盖完整接入流程。API 与 MCP 共用网页版账户的额度、任务队列和历史记录，任务成功后才扣除实际视频时长。

Base URL：https://promptvv.com鉴权：Bearer API Key返回：JSON异步任务

5 分钟快速开始

下面的 Node.js 示例会创建一个链接分析任务，每 3 秒查询一次状态，并在完成后输出结果。需要 Node.js 18 或更高版本。

登录并创建 API Key

在下一节输入一个便于识别的名称并创建密钥。密钥只显示一次，请立即保存。

保存为环境变量

终端

export PROMPTVV_API_KEY='YOUR_API_KEY'

运行完整示例

把示例中的抖音链接替换为真实视频链接，然后保存为 analyze.mjs 并执行 node analyze.mjs。

analyze.mjs

const API_KEY = process.env.PROMPTVV_API_KEY;
const BASE_URL = "https://promptvv.com";

const created = await fetch(`${BASE_URL}/api/v1/analyze`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.douyin.com/video/VIDEO_ID",
  }),
});

if (!created.ok) throw new Error(await created.text());
const job = await created.json();

while (true) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const response = await fetch(`${BASE_URL}/api/v1/jobs/${job.id}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!response.ok) throw new Error(await response.text());

  const current = await response.json();
  if (current.status === "done") {
    console.log(current.result);
    break;
  }
  if (current.status === "error") {
    throw new Error(current.error_code ?? "ANALYSIS_FAILED");
  }
}

创建与管理 API Key

API Key 代表当前账户。不要写入前端代码、公开仓库或日志；一旦泄露，请立即撤销并创建新密钥。VideoFlow 与 PromptVV 的密钥不能跨站使用。

在顶栏登录网页版账户。
输入密钥名称，例如“生产环境”或“本地开发”。
点击“创建密钥”，立即复制完整密钥并存入服务器环境变量。

当前账户还没有 API Key。

HTTP API

所有业务接口都使用 Authorization: Bearer YOUR_API_KEY。请求和响应均为 JSON，上传文件的预签名地址除外。

分析视频链接

支持抖音、小红书和 B 站的视频页及官方短链。其他平台请先下载视频，再使用本地上传流程。

cURL

curl -X POST 'https://promptvv.com/api/v1/analyze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.douyin.com/video/VIDEO_ID"}'

响应：202 Accepted

JSON

{
  "id": "c9aa82c5-79ac-4cb8-9a91-9223dc83b6b8",
  "status": "queued",
  "queued": true
}

上传并分析本地视频

支持 MP4、MOV、WebM、M4V，单个文件最大 500 MB。文件直接上传对象存储，不经过应用服务器。

cURL

# 1. 获取 30 分钟有效的预签名上传地址
curl -X POST 'https://promptvv.com/api/v1/uploads' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"filename":"video.mp4","size_bytes":12345678}'

# 2. 将文件直接 PUT 到上一步返回的 upload_url
curl -X PUT --upload-file './video.mp4' 'UPLOAD_URL'

# 3. 使用上一步响应中的 upload_key 创建分析任务
curl -X POST 'https://promptvv.com/api/v1/analyze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"upload_key":"UPLOAD_KEY","title":"video.mp4"}'

创建上传地址的响应：201 Created

JSON

{
  "upload_key": "uploads/USER_ID/FILE_ID.mp4",
  "upload_url": "https://storage.example.com/...",
  "method": "PUT",
  "expires_in": 1800,
  "max_bytes": 524288000
}

可选分析参数 dims

不传时使用默认值。仅在需要调整输出方向时传入完整 dims 对象。

字段	可选值	默认值
`model`	`flagship, gemini, doubao, gpt`	flagship
`videoType`	`general, short, dance, ecommerce, script, drama, anime`	general
`targetModel`	`allRef, firstFrame, firstFrameRef`	allRef
`beatMode`	`dialogue, action`	dialogue

接口一览

方法	路径	用途
`POST`	`/api/v1/analyze`	提交视频链接或 upload_key，返回异步任务 ID
`POST`	`/api/v1/uploads`	为本地视频创建预签名 PUT 上传地址
`GET`	`/api/v1/jobs/{id}`	查询任务状态、结果或错误码
`GET`	`/api/v1/credits`	查询当前账户可用秒数和套餐状态
`POST`	`/api/mcp`	远程 MCP JSON-RPC 入口

查询余额

cURL

curl 'https://promptvv.com/api/v1/credits' \
  -H 'Authorization: Bearer YOUR_API_KEY'

JSON

{
  "balanceSec": 1800,
  "isPro": true,
  "activePacks": 1
}

异步任务与结果查询

创建任务后保存返回的 id。建议每 3 秒查询一次；到达 done 或 error 后停止轮询。客户端总等待时间可按业务设置为 30 分钟。

cURL

curl 'https://promptvv.com/api/v1/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

status	含义
`queued`	`任务已进入队列，等待处理`
`analyzing`	`正在解析视频、识别语音并生成结果`
`done`	`任务成功，result 中返回结果，成功后扣除实际视频秒数`
`error`	`任务失败，不扣额度，error_code 中返回错误码`

成功响应

JSON

{
  "id": "c9aa82c5-79ac-4cb8-9a91-9223dc83b6b8",
  "status": "done",
  "source_kind": "link",
  "title": "示例视频",
  "result": {
    "text": "完整的视频分析与提示词结果"
  },
  "error_code": null,
  "charged_seconds": 15,
  "created_at": "2026-07-29T08:00:00.000Z",
  "updated_at": "2026-07-29T08:02:10.000Z"
}

失败响应

JSON

{
  "id": "c9aa82c5-79ac-4cb8-9a91-9223dc83b6b8",
  "status": "error",
  "source_kind": "file",
  "title": "video.mp4",
  "result": null,
  "error_code": "ASR_FAILED",
  "charged_seconds": null,
  "created_at": "2026-07-29T08:00:00.000Z",
  "updated_at": "2026-07-29T08:01:20.000Z"
}

MCP 接入

远程 MCP 地址是 https://promptvv.com/api/mcp。适用于支持远程 HTTP MCP 和自定义 Authorization 请求头的客户端。

创建 API Key

使用本页“创建与管理 API Key”生成一个单独用于 MCP 的密钥，便于需要时独立撤销。

加入 MCP 客户端配置

如果使用 Claude Code，可直接运行下面的命令。其他支持远程 HTTP MCP 的客户端，可把 JSON 配置合并进现有配置，不要覆盖已有的 mcpServers。

Claude Code

claude mcp add --transport http promptvv 'https://promptvv.com/api/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY'

mcp.json

{
  "mcpServers": {
    "promptvv": {
      "url": "https://promptvv.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

重启客户端并验证

重启或重新加载 MCP 服务，然后让客户端执行“查询我的剩余额度”。成功时会调用 get_quota 并返回 balanceSec。

不经过客户端的连通性验证

如果客户端显示连接失败，先用以下请求验证地址和密钥。返回 JSON-RPC result 即表示连接正常。

cURL

curl -X POST 'https://promptvv.com/api/mcp' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{"name":"get_quota","arguments":{}}
  }'

可用工具

工具	参数	用途
`get_quota`	`无`	查询与网页版共用的剩余视频秒数
`create_video_upload`	`filename, size_bytes`	为本地视频创建临时 PUT 上传地址
`analyze_video`	`url 或 upload_key；title、dims 可选`	创建异步视频分析任务
`get_analysis`	`id`	查询任务状态、结果和错误码

本地文件工作流：先调用 create_video_upload，用 HTTP PUT 把文件上传至返回的 upload_url，再把 upload_key 交给 analyze_video。如果 MCP 客户端不能读取本地文件或执行 PUT，请改用 HTTP API 完成上传。

错误处理与排查

HTTP 错误统一返回 code、message 和 request_id。联系支持时请附上 request_id、任务 id 和发生时间，不要发送完整 API Key。

错误响应

{
  "code": "QUOTA_INSUFFICIENT",
  "message": "额度不足，请充值",
  "request_id": "82d64113-09b0-473b-a7b5-1f11bbb08f64"
}

HTTP	code	处理方式
`400`	`VALIDATION`	字段缺失、格式错误，或 url 与 upload_key 同时提交
`400`	`LINK_UNSUPPORTED`	链接平台不支持，改用抖音、小红书、B 站链接或本地上传
`400`	`VIDEO_INVALID`	视频格式无法识别，检查文件扩展名和文件内容
`401`	`API_KEY_INVALID`	API Key 错误、已撤销，或来自另一个站点
`402`	`QUOTA_INSUFFICIENT`	额度不足，请先在网页版充值
`403`	`FORBIDDEN`	upload_key 不属于当前账户，请重新创建上传地址
`404`	`NOT_FOUND`	任务不存在，或任务不属于当前账户
`422`	`CONTENT_REJECTED`	内容被安全策略拒绝
`429`	`RATE_LIMITED`	请求过于频繁，等待后重试
`502`	`LINK_FETCH_FAILED / ASR_FAILED / AI_FAILED`	上游解析或分析失败，可稍后重试
`500 / 503`	`INTERNAL / PROVIDER_DOWN`	服务暂时异常，使用指数退避重试

可以自动重试：429、500、502、503。建议等待 2 秒、4 秒、8 秒，最多重试 3 次。

不要直接重试：400、401、402、404、422。先修正参数、密钥、额度或输入内容。