开发者文档

VideoAgain API 与 MCP

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

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

5 分钟快速开始

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

登录并创建 API Key

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

保存为环境变量

终端

export VIDEOAGAIN_API_KEY='YOUR_API_KEY'

运行完整示例

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

analyze.mjs

const API_KEY = process.env.VIDEOAGAIN_API_KEY;
const BASE_URL = "https://staging.videoagain.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" || current.status === "cancelled") {
    throw new Error(current.error_code ?? "ANALYSIS_FAILED");
  }
}

创建与管理 API Key

API Key 代表当前账户。不要写入前端代码、公开仓库或日志；一旦泄露，请立即撤销并创建新密钥。VideoAgain 密钥只用于本站。

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

权限范围

旧密钥默认拥有完整权限；新密钥可按用途缩小范围。权限不足返回 403。

当前账户还没有 API Key。

HTTP API

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

分析视频链接

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

cURL

curl -X POST 'https://staging.videoagain.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、时长不超过 10 分钟。文件直接上传对象存储，不经过应用服务器；服务端探测到超长视频会在分析前返回 VIDEO_TOO_LONG。

cURL

# 1. 获取 30 分钟有效的预签名上传地址
curl -X POST 'https://staging.videoagain.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://staging.videoagain.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/jobs`	稳定游标分页查询任务历史
`POST`	`/api/v1/analyses/batch`	一次提交最多 8 项，逐项返回 accepted/error
`GET`	`/api/v1/capabilities`	读取站点当前能力与限制
`GET`	`/api/v1/credits`	查询当前账户可用秒数和套餐状态
`GET`	`/api/v1/usage`	查询持久化用量账本
`POST`	`/api/v1/jobs/{id}/retry`	重试失败任务
`POST`	`/api/v1/jobs/{id}/cancel`	取消未完成任务并释放预留额度
`POST / GET / DELETE`	`/api/v1/webhooks...`	管理异步完成/失败通知
`POST`	`/api/mcp`	远程 MCP JSON-RPC 入口

查询余额

cURL

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

JSON

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

异步任务与结果查询

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

cURL

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

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

成功响应

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"
}

历史、批量与用量

历史列表使用稳定 keyset 游标，只返回任务卡片字段。cursor 是不透明值，请原样回传。

历史列表

cURL

GET https://staging.videoagain.com/api/v1/jobs?limit=20&status=done  ·  Authorization: Bearer YOUR_API_KEY

JSON

items, has_more, next_cursor  // 继续请求时原样发送 next_cursor

批量提交与幂等

cURL

POST https://staging.videoagain.com/api/v1/analyses/batch  ·  Idempotency-Key: batch-20260805-01  ·  body: { items: [{ client_reference_id, upload_key | url, title, dims }] }

一次最多 8 项，每项独立验证。相同 Idempotency-Key 与请求内容会重放第一次响应，不会重复建任务、扣费或发送队列事件；请求内容不同返回 409 IDEMPOTENCY_CONFLICT。

能力、用量、重试与取消

接口

GET /api/v1/capabilities  ·  GET /api/v1/usage?limit=20  ·  POST /api/v1/jobs/{id}/retry  ·  POST /api/v1/jobs/{id}/cancel

usage 是追加式账本，analysis_charge 为负数，credit_purchase 与 reservation_release 为正数。只有 error 任务可以重试，只有 queued 或 analyzing 任务可以取消。取消会停止后续阶段调度并释放未消费的额度预留。

Webhook

任务完成或失败后，事件先写入数据库 outbox，再由独立投递器异步发送。投递失败不会改变任务状态。

创建

POST https://staging.videoagain.com/api/v1/webhooks  ·  body: { url: "https://example.com/videoagain-hook", events: ["analysis.completed", "analysis.failed"] }

创建成功时 secret 只返回一次。地址必须是 HTTPS 公网地址，禁止 localhost、私网、链路本地、云元数据地址和不安全重定向。服务端保存的是加密密文。

签名验证

Node.js

signed = timestamp + "." + rawBody; expected = HMAC_SHA256(WEBHOOK_SECRET, signed); compare X-Matrix-Signature with sha256=<expected> before JSON.parse; reject timestamps older than 5 minutes; dedupe by event id

请求头包含 X-Matrix-Event-Id、X-Matrix-Delivery-Id、X-Matrix-Timestamp 和 X-Matrix-Signature。2xx 后停止重试；非 2xx、超时、429、500 和连接失败按指数退避与抖动重试，最多 8 次。

MCP 接入

远程 MCP 地址是 https://staging.videoagain.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 videoagain 'https://staging.videoagain.com/api/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY'

mcp.json

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

重启客户端并验证

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

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

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

cURL

curl -X POST 'https://staging.videoagain.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`	查询任务状态、结果和错误码
`list_analyses`	`limit、cursor、status、时间过滤`	稳定游标查询历史任务
`analyze_videos`	`items，最多 8 项`	批量创建任务并逐项返回结果
`get_capabilities`	`无`	查询当前站点能力
`list_usage`	`limit、cursor、type、时间过滤`	读取用量账本
`retry_analysis`	`id`	重试失败任务
`cancel_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`	任务不存在，或任务不属于当前账户
`409`	`IDEMPOTENCY_CONFLICT`	同一个 Idempotency-Key 被用于不同请求内容；换用新 key 或修正请求
`409`	`JOB_NOT_RETRYABLE / JOB_NOT_CANCELLABLE`	任务当前状态不允许重试或取消
`422`	`CONTENT_REJECTED`	内容被安全策略拒绝
`400`	`WEBHOOK_INVALID_URL`	Webhook 必须是 HTTPS 公网地址，不能指向内网或元数据地址
`429`	`RATE_LIMITED`	请求过于频繁，等待后重试
`502`	`LINK_FETCH_FAILED / ASR_FAILED / AI_FAILED`	上游解析或分析失败，可稍后重试
`500 / 503`	`INTERNAL / PROVIDER_DOWN / WEBHOOK_SECRET_UNAVAILABLE`	服务暂时异常，使用指数退避重试

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

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