开放 API 与 MCP 接入文档

XPuzi 同时提供 MCP（给 AI 工具调用）与 REST 开放 API（给网站/平台集成），两者共用同一套 Token 与额度。

去账号中心创建 Token

MCP 端点（Streamable HTTP）

https://vd.xpuzi.com/api/mcp

JSON-RPC 2.0 · 协议版本 2025-06-18

开放 API 根地址

https://vd.xpuzi.com/api/openapi/v1

REST + JSON，统一 success / data 信封

1. 快速开始

注册并按提示验证邮箱或手机号（未验证无法创建 Token）。
在账号中心点击「创建 Token」，明文只在创建时显示一次，请立即保存。
把 Token 填入下面的接入配置，或在账号中心点「一键复制 AI 接入指令」粘贴给豆包 / WorkBuddy 等工具。

鉴权方式

所有请求携带请求头 Authorization: Bearer xpuzi_sk_xxxxxxxx。 Token 只存哈希，遗失只能吊销后重新创建；请勿提交到公开仓库或前端代码。

统一响应结构

成功 / 失败

// 成功
{ "success": true, "data": { ... } }

// 失败（HTTP 4xx / 5xx）
{ "success": false, "code": "QUOTA_EXCEEDED", "message": "今日额度已用完" }

2. MCP 接入

MCP 使用 Streamable HTTP 传输，客户端向 POST /api/mcp 发送 JSON-RPC 2.0 消息即可。支持 initialize、notifications/initialized、ping、tools/list、tools/call。

客户端配置

mcp.json（Claude Desktop / Cursor / Cherry Studio 等）

{
  "mcpServers": {
    "xpuzi": {
      "type": "http",
      "url": "https://vd.xpuzi.com/api/mcp",
      "headers": { "Authorization": "Bearer xpuzi_sk_你的Token" }
    }
  }
}

协议握手示例

initialize

curl -s https://vd.xpuzi.com/api/mcp \
  -H "Authorization: Bearer xpuzi_sk_你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

工具列表

工具	参数	说明
parse_media	url	解析分享链接，返回 parseId、标题、作者、平台、音视频格式与图片数；消耗 1 次解析额度
download_media	parseId \| url, action=video\|audio, formatId?, videoIndex?, audioIndex?	创建下载任务，返回 taskId；消耗 1 次下载额度，失败自动返还
download_images	parseId \| url	图文作品图片打包为 zip；消耗 1 次下载额度
get_task	taskId	查询任务状态：queued / downloading / completed / failed / cancelled
wait_task	taskId, timeoutSeconds≤300	等待任务完成并返回最终状态，默认 60 秒
list_tasks	status?, limit≤100, offset?	分页列出当前 Token 创建的任务
control_task	taskId, action=cancel\|remove\|retry	取消并返还额度 / 删除任务与文件 / 重新下载
extract_audio	taskId	对已完成任务提取音频；消耗 1 次下载额度
get_download_url	taskId	获取 24 小时有效的签名下载直链
get_quota	无	查询今日解析/下载额度使用情况

调用示例

tools/call · parse_media

curl -s https://vd.xpuzi.com/api/mcp \
  -H "Authorization: Bearer xpuzi_sk_你的Token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "parse_media",
      "arguments": { "url": "https://www.bilibili.com/video/BV1xx411c7mD" }
    }
  }'

工具结果放在 result.content[0].text 中，内容是 JSON 字符串，需二次解析。

3. 开放 REST API

方法	路径	说明
GET	/api/openapi/v1/me	查询当前 Token 所属用户、套餐、作用域与限流
POST	/api/openapi/v1/parse	解析链接；body: { url }
POST	/api/openapi/v1/download	创建任务；body: { parseId \| url, action, formatId?, videoIndex?, audioIndex? }
GET	/api/openapi/v1/tasks?status=&limit=&offset=	任务列表
GET	/api/openapi/v1/tasks/{taskId}	任务详情
POST	/api/openapi/v1/tasks/{taskId}/control	body: { action: cancel \| remove \| retry }
GET	/api/openapi/v1/tasks/{taskId}/download-url	签名下载直链（24 小时有效）
GET	/api/openapi/v1/quota	今日配额快照

解析

POST /api/openapi/v1/parse

curl -s -X POST https://vd.xpuzi.com/api/openapi/v1/parse \
  -H "Authorization: Bearer xpuzi_sk_你的Token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.bilibili.com/video/BV1xx411c7mD"}'

// 返回
{
  "success": true,
  "data": {
    "parseId": "b8d7d9711aeb452c9404caf3b11f0c35",
    "platform": "bilibili",
    "title": "……",
    "author": "……",
    "cover": "https://……",
    "images": [],
    "videos": [{ "formatId": "30280", "quality": "1080P", "size": 26463104 }],
    "audios": [{ "formatId": "30280", "label": "audio" }]
  }
}

创建下载任务

POST /api/openapi/v1/download

curl -s -X POST https://vd.xpuzi.com/api/openapi/v1/download \
  -H "Authorization: Bearer xpuzi_sk_你的Token" \
  -H "Content-Type: application/json" \
  -d '{"parseId":"b8d7d9711aeb452c9404caf3b11f0c35","action":"video"}'

// 返回
{ "success": true, "data": { "taskId": "256e7169e03f487ca51433e79c1d2410", "status": "queued" } }

查询任务与下载

GET /api/openapi/v1/tasks/{taskId}

{
  "success": true,
  "data": {
    "taskId": "256e7169e03f487ca51433e79c1d2410",
    "status": "completed",
    "filename": "视频标题.mp4",
    "size": 26463104,
    "expiresAt": 1794194400
  }
}

# 获取直链（24 小时有效，带签名，可直接下载/转存）
curl -s https://vd.xpuzi.com/api/openapi/v1/tasks/256e7169e03f487ca51433e79c1d2410/download-url \
  -H "Authorization: Bearer xpuzi_sk_你的Token"

4. 错误码

HTTP	code	含义
401	UNAUTHORIZED / TOKEN_INVALID	缺少 Token 或 Token 格式错误
401	TOKEN_REVOKED / TOKEN_EXPIRED	Token 已吊销或过期，请重新创建
403	USER_DISABLED	账号被禁用
403	SCOPE_FORBIDDEN	Token 作用域不足
429	RATE_LIMITED	请求过于频繁，建议指数退避重试
402 / 429	QUOTA_EXCEEDED	今日额度已用完，购买套餐或次日恢复
404	TASK_NOT_FOUND	任务不存在或不属于当前账号
409	TASK_NOT_COMPLETED	任务未完成，暂时无法取下载链接
400	INVALID_PARAMS	参数缺失或格式错误
502	UPSTREAM_ERROR	上游解析/下载服务异常，可稍后重试

5. 配额与限制

免费账号每日 20 次；套餐见站点「购买套餐」。解析与下载分别计数，失败会自动返还。
每个 Token 有独立速率限制，触发后返回 429，请勿高频轮询任务状态（建议 2 秒以上间隔）。
parseId 30 分钟内有效，过期需重新解析。
下载文件在服务器保留 24 小时，过期自动清理；签名直链 24 小时内可直接下载。
任务与文件按账号隔离，跨账号访问返回 TASK_NOT_FOUND。

遇到接入问题可在反馈页留言，或到账号中心复制完整的 AI 接入指令，让 AI 工具按文档自动完成联调。