视频知识提取专家

视频转文字开放 API
四类平台,一套接口

谛听AI 开放 API:一个接口批量转写 B站多P、抖音、小红书与本地视频,消耗账号套餐内额度
01

一把 Key 覆盖四类平台

B站(含多P合集)、抖音、小红书、本地文件,鉴权方式相同

02

逐字稿带时间戳

同时返回纯文本与带时间戳版本,可定位回原声核对

03

异步任务模型

提交即返回 taskId,轮询取结果,适合长视频与批量任务

04

支持批量提交

B站多P与多文件上传均可一次提交多个任务

获取 API Key
← 返回谛听AI 首页

v1 · 最后更新 2026-11-11 · 适用域名 api.diting.cc · 下载 OpenAPI 3.0 规范

能力与端点

开放 API 与网页端接口是两套独立入口:开放 API 只挂在 /v1 下,仅接受 API Key,限流与上传上限独立计算。

能力方法与路径说明
元数据探测POST /v1/transcriptions/{platform}/checkplatform 取 bilibili / douyin / xhs,用于取标题与时长的提交前置步骤
提交转写POST /v1/transcriptions/bilibili多P合集,一次可提交多个分P
提交转写POST /v1/transcriptions/douyin抖音链接或 App 分享文案
提交转写POST /v1/transcriptions/xhs小红书,请求体与抖音一致
提交转写POST /v1/transcriptions/uploadmultipart/form-data,支持多文件
查询结果GET /v1/transcriptions/{taskId}返回状态、逐字稿、带时间戳版本与摘要
用量查询GET /v1/usage本 Key 今日调用量与近 7 天趋势

鉴权

在控制台「API Keys」页创建密钥,格式为 sk-diting- 前缀。密钥仅在创建时完整展示一次。

只支持两种请求头写法,推荐第一种:

Authorization: Bearer sk-diting-xxxxxxxx      # 推荐
X-API-Key: sk-diting-xxxxxxxx

不再支持把 Key 放在 URL 参数里(?api_key=):URL 会被写进访问日志,等于把明文密钥留在日志中,存在泄露风险。

鉴权失败返回 401 与错误码 E2002。

快速开始

完整链路分三步:探测元数据、提交任务、轮询结果。以抖音为例:

# 1. 探测标题与时长
curl -X POST https://api.diting.cc/v1/transcriptions/douyin/check \
  -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://v.douyin.com/xxxxxx/"}'

# 2. 提交转写任务(duration 必填,单位秒)
curl -X POST https://api.diting.cc/v1/transcriptions/douyin \
  -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://v.douyin.com/xxxxxx/","title":"视频标题","duration":620}'

# 3. 轮询结果
curl -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  https://api.diting.cc/v1/transcriptions/<taskId>
提交前必须先探测:服务端需要用视频时长做额度校验。若跳过这一步导致 duration 缺失,请求会被拒绝,避免出现「已受理但跑完才发现额度不足」。

示例代码

两段可直接运行的完整示例,覆盖「探测 → 提交 → 轮询」全链路,含 429 退避处理。

Python

import time

import requests

API_KEY = "sk-diting-xxxxxxxx"
BASE = "https://api.diting.cc"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
VIDEO_URL = "https://v.douyin.com/xxxxxx/"


def post(path, payload):
    r = requests.post(BASE + path, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]


# 1) 探测元数据(duration 是提交的必填项)
meta = post("/v1/transcriptions/douyin/check", {"video_url": VIDEO_URL})

# 2) 提交任务
task = post("/v1/transcriptions/douyin", {
    "video_url": VIDEO_URL,
    "title": meta.get("title", ""),
    "duration": meta["duration"],
})
task_id = task["task_id"]

# 3) 轮询:指数退避,遇到 429 按 Retry-After 等待
delay = 5
for _ in range(200):
    r = requests.get(BASE + "/v1/transcriptions/" + task_id, headers=HEADERS, timeout=30)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "10")))
        continue
    r.raise_for_status()
    data = r.json()["data"]
    if data["status"] == "completed":
        print(data["text"])
        break
    if data["status"] in ("failed", "cancelled"):
        raise SystemExit(data.get("errorMessage", "任务失败"))
    time.sleep(delay)
    delay = min(delay * 2, 30)
else:
    raise SystemExit("轮询超时")

Node.js(18+,使用内置 fetch)

const API_KEY = "sk-diting-xxxxxxxx";
const BASE = "https://api.diting.cc";
const HEADERS = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};
const VIDEO_URL = "https://v.douyin.com/xxxxxx/";

async function post(path, payload) {
  const res = await fetch(BASE + path, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(payload),
  });
  if (!res.ok) throw new Error(path + " -> " + res.status);
  return (await res.json()).data;
}

async function main() {
  // 1) 探测元数据
  const meta = await post("/v1/transcriptions/douyin/check", { video_url: VIDEO_URL });

  // 2) 提交任务
  const task = await post("/v1/transcriptions/douyin", {
    video_url: VIDEO_URL,
    title: meta.title,
    duration: meta.duration,
  });

  // 3) 轮询:指数退避,遇到 429 按 Retry-After 等待
  let delay = 5000;
  for (let i = 0; i < 200; i += 1) {
    const url = BASE + "/v1/transcriptions/" + task.task_id;
    const res = await fetch(url, { headers: HEADERS });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 10) * 1000;
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }
    const data = (await res.json()).data;
    if (data.status === "completed") return data.text;
    if (data.status === "failed" || data.status === "cancelled") {
      throw new Error(data.errorMessage || "任务失败");
    }
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 30000);
  }
  throw new Error("轮询超时");
}

main()
  .then((text) => console.log(text))
  .catch((err) => {
    console.error(err);
    process.exit(1);
  });
示例中的 duration 直接取自探测结果。B站多P需要先取 parts[],把每个分P的 url、thumbnail、title、duration 组成 videos 数组一次提交。

接口说明

每个接口都给出「请求参数」与「响应字段」两张表。响应统一包在 { code, message, data, error } 信封里,下面示例展示的是 data 的内容(上传接口除外,见该节说明)。

code 是 HTTP 状态码(数字),成功为 200;业务错误码在 error.error_code 里,形如 E2010。两处都要判断:先看 code 决定是否重试,再看 error_code 决定是退避、充值还是改参数。

1. 元数据探测

POST /v1/transcriptions/{platform}/check

提交转写前必须先探测一次:服务端要用返回的 duration 做额度校验。

参数类型必填说明示例
video_urlstring是视频链接;抖音/小红书也可传 App 分享出来的整段文案https://v.douyin.com/xxxxxx/

请求示例({platform} 取 bilibili / douyin / xhs):

curl -X POST https://api.diting.cc/v1/transcriptions/douyin/check \
  -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://v.douyin.com/xxxxxx/"}'

抖音 / 小红书的响应 data:

{
  "platform": "douyin",
  "title": "视频标题",
  "duration": 620,
  "cover": "https://...jpg",
  "author": "作者昵称",
  "video_url_resolved": "https://www.douyin.com/video/xxxx",
  "probe_failed": false
}

B站返回的是另一套结构:字段来自 B站解析结果,没有 platform 与 probe_failed,时长是字符串,封面字段名为 thumbnail。

{
  "is_multi_part": true,
  "video_type": "multi_part",
  "title": "合集标题",
  "duration": "62:00",
  "thumbnail": "https://i0.hdslb.com/bfs/archive/cover.jpg",
  "parts": [
    {
      "part_index": 1,
      "title": "P1 第一集",
      "duration": "12:30",
      "url": "https://www.bilibili.com/video/BVxxxx?p=1",
      "bvid": "BVxxxx",
      "thumbnail": "https://i0.hdslb.com/bfs/archive/cover1.jpg"
    },
    {
      "part_index": 2,
      "title": "P2 第二集",
      "duration": "18:45",
      "url": "https://www.bilibili.com/video/BVxxxx?p=2",
      "bvid": "BVxxxx",
      "thumbnail": "https://i0.hdslb.com/bfs/archive/cover2.jpg"
    }
  ],
  "season_id": 0
}
两类平台的时长单位不同是历史原因:抖音/小红书是 秒(int),B站是 MM:SS 字符串。提交时原样传回即可,不要自己换算。B站 parts[] 还会返回 aid、cid、pubdate、view、danmaku 等字段,按需取用。

抖音 / 小红书响应字段:

字段类型说明
platformstring平台标识:douyin 或 xhs
titlestring视频标题,可直接作为提交时的 title
durationint视频时长(秒),提交时用它做额度校验
coverstring封面地址,可填入提交时的 thumbnail
authorstring作者昵称,可能为空(平台侧不一定拿得到)
video_url_resolvedstring短链解析后的标准页地址,排查播放问题时可对照
probe_failedbooltrue 表示没拿到标题或时长,此时不要直接提交,请换链接或改走文件上传

B站响应字段:

字段类型说明
is_multi_partbool是否为多P合集
video_typestringsingle / multi_part / collection
titlestring视频标题
durationstring视频总时长,MM:SS 字符串
thumbnailstring封面地址(注意不是 cover)
parts[]array分P列表,单P视频也只有一项
parts[].part_indexint分P序号,从 1 开始
parts[].titlestring分P标题
parts[].durationstring分P时长,MM:SS 字符串
parts[].urlstring分P完整链接,可直接填入提交的 videos[].url
parts[].bvidstring该分P所属视频的 BV 号
parts[].thumbnailstring分P封面,可直接填入 videos[].thumbnail
season_idint合集 ID,仅合集视频有值

2. 提交转写 — B站

POST /v1/transcriptions/bilibili
参数类型必填说明示例
videosarray是分P数组,一次可提交多集见下方请求体
videos[].urlstring是分P完整链接,直接取探测结果的 parts[].urlhttps://www.bilibili.com/video/BVxxxx?p=1
videos[].thumbnailstring是封面地址https://i0.hdslb.com/bfs/archive/cover1.jpg
videos[].titlestring是分P标题P1 第一集
videos[].durationstring是MM:SS 或 HH:MM:SS 字符串,不是秒数"12:30"
languagestring否ISO 639-1,留空按中文链路处理"zh"

请求体示例(两个分P一次提交,字段值全部来自上一步探测):

{
  "videos": [
    {
      "url": "https://www.bilibili.com/video/BVxxxx?p=1",
      "thumbnail": "https://i0.hdslb.com/bfs/archive/cover1.jpg",
      "title": "P1 第一集",
      "duration": "12:30"
    },
    {
      "url": "https://www.bilibili.com/video/BVxxxx?p=2",
      "thumbnail": "https://i0.hdslb.com/bfs/archive/cover2.jpg",
      "title": "P2 第二集",
      "duration": "18:45"
    }
  ],
  "language": "zh"
}

响应:success_count 加 failed_count 等于 total_count;被拒的分P不会出现在 task_ids 里,失败原因在 failed_files[]。

{
  "success": true,
  "task_ids": ["tsk_20261111_aaa", "tsk_20261111_bbb"],
  "success_count": 2,
  "failed_count": 0
  "total_count": 2
}

响应字段:

字段类型说明
successbool本次请求是否整体成功;部分分P失败时为 true 但 failed_count 大于 0,要分别判断
task_idsarray受理成功的任务号,只含成功的分P,不要用下标去对应提交顺序
file_namesarray与 task_ids 一一对应的文件名
success_countint受理成功的分P数
failed_countint未受理的分P数
total_countint本次提交的分P总数
failed_files[]array失败明细,每项含 url、title、error(失败原因)
deductionobject额度抵扣信息,含 orderId、orderDuration、videoDuration、remainingDuration

3. 提交转写 — 抖音 / 小红书

POST /v1/transcriptions/douyin | /v1/transcriptions/xhs
参数类型必填说明示例
video_urlstring是链接或 App 分享文案https://v.douyin.com/xxxxxx/
titlestring否取自探测结果视频标题
durationint是时长(秒),取自探测结果620
thumbnailstring否封面地址https://.../cover.jpg
languagestring否ISO 639-1"zh"

请求示例(小红书把路径换成 /v1/transcriptions/xhs,请求体完全一致):

curl -X POST https://api.diting.cc/v1/transcriptions/douyin \
  -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://v.douyin.com/xxxxxx/","title":"视频标题","duration":620,"language":"zh"}'

响应:

{ "task_id": "tsk_...", "file_name": "...", "platform": "douyin" }

响应字段:

字段类型说明
task_idstring任务号,用它轮询 GET /v1/transcriptions/{taskId}
file_namestring该任务的文件名标识,多任务并存时用于区分
platformstring平台标识:douyin 或 xhs

4. 提交转写 — 本地文件

POST /v1/transcriptions/upload(multipart/form-data)
字段类型必填说明示例
filefile是文件字段名固定为 file,可重复传多个-F "file=@lecture.mp4"
languagestring否ISO 639-1-F "language=zh"
curl -X POST https://api.diting.cc/v1/transcriptions/upload \
  -H "Authorization: Bearer sk-diting-xxxxxxxx" \
  -F "file=@lecture.mp4" \
  -F "language=zh"

响应比其它接口多一层嵌套,任务号在 data.data.task_ids:

{ "success": true, "data": { "task_ids": ["tsk_..."], "success_count": 1 } }

单文件上限默认 200MB,超限返回 413 与 E2011。网页端上传上限为 5GB,两者独立。

响应字段(注意这一节是完整信封,业务数据在 data 里再嵌一层):

字段类型说明
successbool本次上传是否整体成功
data.task_idsarray受理成功的任务号,多文件时按提交顺序排列
data.success_countint受理成功的文件数

任务状态

GET /v1/transcriptions/{taskId}

同一个接口既查进度也取结果。处理中时 text 为空,返回状态与进度:

{
  "taskId": "tsk_20261111_aaa",
  "status": "processing",
  "progress": 40,
  "sourceType": "bilibili",
  "fileName": "P1.mp4",
  "durationSeconds": 630,
  "text": "",
  "createdAt": "2026-11-11T12:00:00+08:00"
}

取到结果时(字段完整):

{
  "taskId": "tsk_20261111_aaa",
  "status": "completed",
  "progress": 100,
  "sourceType": "bilibili",
  "fileName": "P1.mp4",
  "durationSeconds": 630,
  "text": "逐字稿正文……",
  "textWithTimestamp": "[00:00] 第一句……",
  "summary": "结构化摘要……",
  "createdAt": "2026-11-11T12:00:00+08:00",
  "completedAt": "2026-11-11T12:26:00+08:00"
}
示例里的时间戳只是格式示意,实际耗时取决于视频时长、网络与当前队列。

响应字段:

字段类型说明
taskIdstring任务号,与提交时返回的一致
statusstring任务状态,取值见下方状态表
progressint进度百分比,0–100
sourceTypestring来源类型:bilibili / douyin / xhs / upload
fileNamestring该任务对应的文件名
durationSecondsint视频时长(秒)
textstring逐字稿纯文本;尚未生成时为空字符串
textWithTimestampstring带时间戳的逐字稿,用于定位回原声核对
summarystring结构化摘要;摘要阶段未完成时可能为空
createdAtstring任务创建时间,ISO 8601
completedAtstring完成时间,ISO 8601;未完成时不返回
errorCodestring仅 failed 时返回,取值同下方错误码表
errorMessagestring仅 failed 时返回,失败原因描述

状态取值:

status含义处理建议
queued已受理,等待处理继续轮询
processing处理中(下载、抽音频、转写、摘要、脑图)继续轮询
completed全部完成取 text,停止轮询
failed处理失败查看 errorCode 与 errorMessage
cancelled已取消重新提交
text 在逐字稿生成后即可取回,不必等 status 变为 completed。长视频在摘要与脑图阶段仍需时间,但正文此时已经可用。

轮询建议:第一分钟每 5 秒一次,之后放宽到 15 至 30 秒;单任务频率不要超过 1 次 / 2 秒,否则容易触发限流。

限流与额度

  • 限流:默认每个 Key 每分钟 60 次、每天 5000 次,超限返回 429 与 E2010,响应头 Retry-After 给出建议等待秒数。
  • 额度:开放 API 消耗账号套餐内的转写时长,与网页端同源;不足返回 402。
  • 免费区间:单条视频时长不超过 300 秒(5 分钟)时整体不计费;超过则按完整时长计入,按分钟向上取整(12:30 计 13 分钟)。
  • 多P合计:B站多P 一次请求计算所有分P的时长之和。额度不足时整个请求被拒绝,不会创建任何一个任务。
  • 隔离:限流、上传上限、路由均与网页端独立,第三方调用不会占用网页用户的每日次数。

额度自查

GET /v1/usage 同时返回调用量与额度快照。两者口径不同:调用量是观测口径(记的是「调了几次」),额度是订单口径(与提交时的校验完全一致)。

额度快照有 10 秒缓存:充值到账、任务刚扣费或刚提交在途任务后,最多 10 秒才会反映到该字段。别把它当成逐秒实时的余额。
{
  "keyId": "key_xxxx",
  "today": "2026-11-12",
  "todayRequests": 42,
  "recentDays": [{ "date": "2026-11-12", "requests": 42 }],
  "limits": { "perMinute": 60, "perDay": 5000 },
  "availableMinutes": 12,
  "pendingMinutes": 5,
  "totalMinutes": 30,
  "usedMinutes": 13,
  "unlimited": false,
  "note": "..."
}
字段类型说明
availableMinutesint | null真实可用 = 总额度 − 已用 − 在途预占。不限时长套餐与查询降级时为 null
pendingMinutesint | null在途任务(已提交未扣费)已预占的分钟数
totalMinutesint | null本窗口总额度,含时长包池
usedMinutesint | null本窗口已扣分钟数,含包池已用
unlimitedbool | nulltrue 表示不限时长套餐,此时 availableMinutes 为 null
额度字段为 null 表示暂时查不到(统计服务降级),与 0(额度确实用完)含义完全不同:前者可以继续提交,后者提交必被 402 拒绝。不要把 null 当成 0,否则会在服务波动时误停所有任务。

提交前自查,避免被 402 打断:

# 1) 探测拿到时长(不消耗额度)
# 2) 查可用额度
# 3) 需要分钟数 = ceil(时长秒数 / 60),不超过 300 秒则不计费
# 4) 不够就先等(pendingMinutes 会随在途任务完成而释放)或升级套餐

错误码

响应统一为 { code, message, data, error }。code 是 HTTP 状态码(数字),成功为 200;业务错误码在 error.error_code 里。两处都要判断:

# 密钥无效 → HTTP 401
{
  "code": 401,
  "message": "API Key 无效或已失效",
  "error": { "error_code": "E2002", "message": "API Key 无效或已失效", "detail": "..." }
}

# 请求频率超限 → HTTP 429,响应头带 Retry-After
{
  "code": 429,
  "message": "请求频率超限",
  "error": { "error_code": "E2010", "message": "请求频率超限", "detail": "..." }
}

信封字段:

字段类型说明
codeintHTTP 状态码,成功为 200,失败取下方错误码表里的 HTTP 列
messagestring可读描述,成功时为 success,可直接记进日志
dataobject成功时的业务数据(结构见各接口的响应字段表);失败时不返回该字段
errorobject失败时返回,含 error_code(业务错误码)、message、detail(排查细节)

错误码清单(下表的 code 指 error.error_code):

error_codeHTTP含义处置
E1004400参数错误检查 detail 里的字段提示
E2002401API Key 无效或已失效重新签发
E2004402账号可用时长不足充值或升级套餐
E2005402AI 功能配额不足升级套餐
E2008429账号当日提交次数达上限次日再试
E2009429该账号排队任务数超上限等待已有任务完成
E2010429请求频率超限(按 Key)按 Retry-After 退避
E2011413上传文件超过开放 API 上限压缩或改用链接
E3001 / E3002404任务或资源不存在核对 taskId
E0001500服务内部错误重试并联系支持

区分额度类与节奏类:E2008 是今天不能再用,E2010 是放慢调用即可恢复,两者的处理方式不同。

常见问题

支持哪些平台?

B站(含多P合集)、抖音、小红书,以及本地文件上传。其它平台暂未开放,可先用本地文件方式提交。

能一次提交多个视频吗?

可以。B站的 videos 数组与上传接口的多文件都支持批量,返回的 task_ids 与提交顺序一一对应。

有没有 Webhook 回调?

当前为轮询模型。回调在规划中,上线时以新增字段方式提供,不影响现有调用。

转写需要多久?

取决于视频时长、网络与当前队列,不同素材差异较大。请按 status 轮询判断,不要按固定时间预期。

任务结果保留多久?

与账号套餐的存储策略一致。需要长期保存请在拿到结果后自行落库。

企业定制

批量调用配额、接口联调、合同与发票等需求,可以单独沟通。

邮箱:contact@diting.cc

谛听创始人微信二维码,备注企业定制优先响应
扫码加创始人微信
备注「企业定制」,优先响应
返回首页 获取 API Key

适用场景

内容平台批量搬运 企业知识库入库 课程与访谈素材归档 二次剪辑取文案 舆情与合规抽检 自建 Agent 视频理解