videoseed API

用 HTTP API 把视频反解成可直接喂给即梦 / Seedance 的提示词。和网页版共用额度、任务队列和历史记录，任务成功后才扣除实际视频时长。

Base URL·https://www.videoseed.cc鉴权·Bearer API Key（sk_…）返回·JSON · 异步任务限流·60 次 / 分钟 / Key

5 分钟快速开始

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

登录并创建 API Key

打开账户页的 API Key 栏目，输入便于识别的名称并创建密钥。密钥只显示一次，请立即保存。

保存为环境变量

export VIDEOSEED_API_KEY='YOUR_API_KEY'

运行完整示例

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

const API_KEY = process.env.VIDEOSEED_API_KEY;
const BASE_URL = "https://www.videoseed.cc";

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 代表当前账户。不要写入前端代码、公开仓库或日志；一旦泄露，请立即撤销并创建新密钥。网页会话 cookie 打不开 /api/v1/*，API Key 也打不开网页 /api/*。密钥管理已迁到账户设置页。

登录网页版账户。
在账户页「API Key」栏目创建密钥，按需缩小权限范围。
立即复制完整密钥并存入服务器环境变量。

未登录会先弹出登录框；创建与撤销都在账户页完成。

HTTP API

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

分析视频链接

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

curl -X POST 'https://www.videoseed.cc/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

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

上传并分析本地视频

支持 MP4、MOV、WebM、M4V，单个文件最大 500 MB、时长不超过 30 分钟。文件直接上传对象存储，不经过应用服务器；服务端探测到超限会在分析前返回错误码。

# 1. 获取预签名上传地址
curl -X POST 'https://www.videoseed.cc/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://www.videoseed.cc/api/v1/analyze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"upload_key":"UPLOAD_KEY","title":"video.mp4"}'

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

{
  "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	gemini
videoType	general, short, dance, ecommerce, script, drama, anime	general
targetModel	allRef, firstFrame, firstFrameRef	allRef
beatMode	dialogue, action	dialogue
maxSegmentSec	整数秒 5–120（网页默认 15/30/自定义）	15

接口一览

Method	Path
POST	/api/v1/analyze	submit url or upload_key
POST	/api/v1/uploads	presigned PUT
GET	/api/v1/jobs/{id}	status and result
GET	/api/v1/jobs/{id}/video-link	play / download
GET	/api/v1/jobs	history (cursor)
POST	/api/v1/analyses/batch	batch ≤8
GET	/api/v1/capabilities	limits
GET	/api/v1/credits	credits
GET	/api/v1/usage	usage ledger
POST	/api/v1/jobs/{id}/retry	retry
POST	/api/v1/jobs/{id}/cancel	cancel
POST / GET / DELETE	/api/v1/webhooks…	async notifications

查询余额

curl 'https://www.videoseed.cc/api/v1/credits' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

异步任务与结果查询

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

curl 'https://www.videoseed.cc/api/v1/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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

成功响应

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

失败响应

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

按需获取视频链接

done 任务不会在历史或普通结果中自动附带 URL。须按需调用。play 返回 R2 自定义域直链（https://r2.videoseed.cc/…?e=<expires>，不随 expires_in 失效；e 只为覆盖写入后 bust 缓存），不再额外 HEAD；download 仍为带附件头的短时预签名（10 分钟），签发前 HEAD 校验非空 video/mp4。

curl 'https://www.videoseed.cc/api/v1/jobs/JOB_ID/video-link?mode=play' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://www.videoseed.cc/api/v1/jobs/JOB_ID/video-link?mode=download' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "url": "https://r2.videoseed.cc/upload/<sha>/video/source.mp4?e=1757673064",
  "mode": "play",
  "expires_in": 1800,
  "expires_at": "2026-08-10T00:30:00.000Z",
  "content_type": "video/mp4",
  "filename": "示例视频.mp4"
}

历史、批量与用量

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

历史列表

GET https://www.videoseed.cc/api/v1/jobs?limit=20&status=done
Authorization: Bearer YOUR_API_KEY

响应：items / has_more / next_cursor

批量提交与幂等

POST https://www.videoseed.cc/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（含 video_links：play 1800 秒、download 600 秒）
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 / cancelled 可重试（工作台写「重跑」）。提交后不支持取消，POST /cancel 一律 409 JOB_NOT_CANCELLABLE。成功后普通人不能再重跑。

Webhook

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

需要 scope webhooks:manage。

POST /api/v1/webhooks
{ "url": "https://your-server.example/hook", "events": ["analysis.completed", "analysis.failed"] }
→ 201，secret 只回一次（whsec_…）

GET /api/v1/webhooks → 列表（不含 secret）
DELETE /api/v1/webhooks/{id} → { "ok": true }

URL 必须 HTTPS 公网；localhost、私网、链路本地、云元数据地址会被拒（400 WEBHOOK_INVALID_URL）。
投递器不跟随重定向。

请求头：X-Videoseed-Event-Id、X-Videoseed-Delivery-Id、X-Videoseed-Timestamp、X-Videoseed-Signature
签名：sha256=HMAC_SHA256(secret, timestamp + "." + rawBody)
非 2xx / 超时按指数退避重试，最多 8 次后置 failed。

// 接收端：先验签再 JSON.parse；拒绝 >5 分钟的时间戳；按 event_id 去重
const ts = req.headers['x-videoseed-timestamp'];
const sig = req.headers['x-videoseed-signature'];
const raw = await readRawBody(req);
if (!verifyHmac(secret, ts, raw, sig)) return res.status(401).end();
const payload = JSON.parse(raw);

错误处理与排查

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	链接平台不支持
400	VIDEO_INVALID	视频格式无法识别
400	WEBHOOK_INVALID_URL	Webhook URL 不是 HTTPS 公网地址
401	API_KEY_INVALID	Key 错误、已撤销，或凭证越界
402	QUOTA_INSUFFICIENT	额度不足
403	FORBIDDEN	upload_key 不属于当前账户，或 scope 不足
404	NOT_FOUND	任务不存在或不属于当前账户
404	VIDEO_NOT_AVAILABLE	无可回放产物或对象已清理
409	IDEMPOTENCY_CONFLICT	同一 Idempotency-Key 用于不同内容
409	JOB_NOT_RETRYABLE / JOB_NOT_CANCELLABLE	当前状态不允许
422	CONTENT_REJECTED	内容被安全策略拒绝
—	LINK_NO_VIDEO	任务已入队；worker 探测无视频后 error 并实扣 3 秒（图文 / 空列表 / 直播结束等）。创建接口不再因此 422
—	UPLOAD_NO_VIDEO	任务已入队；worker 读对象头后判定不是可处理视频（图片 / 音频 / PDF / 损坏容器），error 并释放预留。创建接口不再因此 422。sts 拦扩展名/MIME 仍 422
429	RATE_LIMITED	过于频繁（>60/min）
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。