B站(含多P合集)、抖音、小红书、本地文件,鉴权方式相同
同时返回纯文本与带时间戳版本,可定位回原声核对
提交即返回 taskId,轮询取结果,适合长视频与批量任务
B站多P与多文件上传均可一次提交多个任务
开放 API 与网页端接口是两套独立入口:开放 API 只挂在 /v1 下,仅接受 API Key,限流与上传上限独立计算。
| 能力 | 方法与路径 | 说明 |
|---|---|---|
| 元数据探测 | POST /v1/transcriptions/{platform}/check | platform 取 bilibili / douyin / xhs,用于取标题与时长的提交前置步骤 |
| 提交转写 | POST /v1/transcriptions/bilibili | 多P合集,一次可提交多个分P |
| 提交转写 | POST /v1/transcriptions/douyin | 抖音链接或 App 分享文案 |
| 提交转写 | POST /v1/transcriptions/xhs | 小红书,请求体与抖音一致 |
| 提交转写 | POST /v1/transcriptions/upload | multipart/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 退避处理。
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("轮询超时")
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 决定是退避、充值还是改参数。提交转写前必须先探测一次:服务端要用返回的 duration 做额度校验。
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
video_url | string | 是 | 视频链接;抖音/小红书也可传 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
}
MM:SS 字符串。提交时原样传回即可,不要自己换算。B站 parts[] 还会返回 aid、cid、pubdate、view、danmaku 等字段,按需取用。抖音 / 小红书响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
platform | string | 平台标识:douyin 或 xhs |
title | string | 视频标题,可直接作为提交时的 title |
duration | int | 视频时长(秒),提交时用它做额度校验 |
cover | string | 封面地址,可填入提交时的 thumbnail |
author | string | 作者昵称,可能为空(平台侧不一定拿得到) |
video_url_resolved | string | 短链解析后的标准页地址,排查播放问题时可对照 |
probe_failed | bool | true 表示没拿到标题或时长,此时不要直接提交,请换链接或改走文件上传 |
B站响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
is_multi_part | bool | 是否为多P合集 |
video_type | string | single / multi_part / collection |
title | string | 视频标题 |
duration | string | 视频总时长,MM:SS 字符串 |
thumbnail | string | 封面地址(注意不是 cover) |
parts[] | array | 分P列表,单P视频也只有一项 |
parts[].part_index | int | 分P序号,从 1 开始 |
parts[].title | string | 分P标题 |
parts[].duration | string | 分P时长,MM:SS 字符串 |
parts[].url | string | 分P完整链接,可直接填入提交的 videos[].url |
parts[].bvid | string | 该分P所属视频的 BV 号 |
parts[].thumbnail | string | 分P封面,可直接填入 videos[].thumbnail |
season_id | int | 合集 ID,仅合集视频有值 |
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
videos | array | 是 | 分P数组,一次可提交多集 | 见下方请求体 |
videos[].url | string | 是 | 分P完整链接,直接取探测结果的 parts[].url | https://www.bilibili.com/video/BVxxxx?p=1 |
videos[].thumbnail | string | 是 | 封面地址 | https://i0.hdslb.com/bfs/archive/cover1.jpg |
videos[].title | string | 是 | 分P标题 | P1 第一集 |
videos[].duration | string | 是 | MM:SS 或 HH:MM:SS 字符串,不是秒数 | "12:30" |
language | string | 否 | 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
}
响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 本次请求是否整体成功;部分分P失败时为 true 但 failed_count 大于 0,要分别判断 |
task_ids | array | 受理成功的任务号,只含成功的分P,不要用下标去对应提交顺序 |
file_names | array | 与 task_ids 一一对应的文件名 |
success_count | int | 受理成功的分P数 |
failed_count | int | 未受理的分P数 |
total_count | int | 本次提交的分P总数 |
failed_files[] | array | 失败明细,每项含 url、title、error(失败原因) |
deduction | object | 额度抵扣信息,含 orderId、orderDuration、videoDuration、remainingDuration |
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
video_url | string | 是 | 链接或 App 分享文案 | https://v.douyin.com/xxxxxx/ |
title | string | 否 | 取自探测结果 | 视频标题 |
duration | int | 是 | 时长(秒),取自探测结果 | 620 |
thumbnail | string | 否 | 封面地址 | https://.../cover.jpg |
language | string | 否 | 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_id | string | 任务号,用它轮询 GET /v1/transcriptions/{taskId} |
file_name | string | 该任务的文件名标识,多任务并存时用于区分 |
platform | string | 平台标识:douyin 或 xhs |
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
file | file | 是 | 文件字段名固定为 file,可重复传多个 | -F "file=@lecture.mp4" |
language | string | 否 | 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 里再嵌一层):
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 本次上传是否整体成功 |
data.task_ids | array | 受理成功的任务号,多文件时按提交顺序排列 |
data.success_count | int | 受理成功的文件数 |
同一个接口既查进度也取结果。处理中时 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"
}
响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
taskId | string | 任务号,与提交时返回的一致 |
status | string | 任务状态,取值见下方状态表 |
progress | int | 进度百分比,0–100 |
sourceType | string | 来源类型:bilibili / douyin / xhs / upload |
fileName | string | 该任务对应的文件名 |
durationSeconds | int | 视频时长(秒) |
text | string | 逐字稿纯文本;尚未生成时为空字符串 |
textWithTimestamp | string | 带时间戳的逐字稿,用于定位回原声核对 |
summary | string | 结构化摘要;摘要阶段未完成时可能为空 |
createdAt | string | 任务创建时间,ISO 8601 |
completedAt | string | 完成时间,ISO 8601;未完成时不返回 |
errorCode | string | 仅 failed 时返回,取值同下方错误码表 |
errorMessage | string | 仅 failed 时返回,失败原因描述 |
状态取值:
| status | 含义 | 处理建议 |
|---|---|---|
queued | 已受理,等待处理 | 继续轮询 |
processing | 处理中(下载、抽音频、转写、摘要、脑图) | 继续轮询 |
completed | 全部完成 | 取 text,停止轮询 |
failed | 处理失败 | 查看 errorCode 与 errorMessage |
cancelled | 已取消 | 重新提交 |
text 在逐字稿生成后即可取回,不必等 status 变为 completed。长视频在摘要与脑图阶段仍需时间,但正文此时已经可用。轮询建议:第一分钟每 5 秒一次,之后放宽到 15 至 30 秒;单任务频率不要超过 1 次 / 2 秒,否则容易触发限流。
429 与 E2010,响应头 Retry-After 给出建议等待秒数。402。300 秒(5 分钟)时整体不计费;超过则按完整时长计入,按分钟向上取整(12:30 计 13 分钟)。GET /v1/usage 同时返回调用量与额度快照。两者口径不同:调用量是观测口径(记的是「调了几次」),额度是订单口径(与提交时的校验完全一致)。
{
"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": "..."
}
| 字段 | 类型 | 说明 |
|---|---|---|
availableMinutes | int | null | 真实可用 = 总额度 − 已用 − 在途预占。不限时长套餐与查询降级时为 null |
pendingMinutes | int | null | 在途任务(已提交未扣费)已预占的分钟数 |
totalMinutes | int | null | 本窗口总额度,含时长包池 |
usedMinutes | int | null | 本窗口已扣分钟数,含包池已用 |
unlimited | bool | null | true 表示不限时长套餐,此时 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": "..." }
}
信封字段:
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | HTTP 状态码,成功为 200,失败取下方错误码表里的 HTTP 列 |
message | string | 可读描述,成功时为 success,可直接记进日志 |
data | object | 成功时的业务数据(结构见各接口的响应字段表);失败时不返回该字段 |
error | object | 失败时返回,含 error_code(业务错误码)、message、detail(排查细节) |
错误码清单(下表的 code 指 error.error_code):
| error_code | HTTP | 含义 | 处置 |
|---|---|---|---|
E1004 | 400 | 参数错误 | 检查 detail 里的字段提示 |
E2002 | 401 | API Key 无效或已失效 | 重新签发 |
E2004 | 402 | 账号可用时长不足 | 充值或升级套餐 |
E2005 | 402 | AI 功能配额不足 | 升级套餐 |
E2008 | 429 | 账号当日提交次数达上限 | 次日再试 |
E2009 | 429 | 该账号排队任务数超上限 | 等待已有任务完成 |
E2010 | 429 | 请求频率超限(按 Key) | 按 Retry-After 退避 |
E2011 | 413 | 上传文件超过开放 API 上限 | 压缩或改用链接 |
E3001 / E3002 | 404 | 任务或资源不存在 | 核对 taskId |
E0001 | 500 | 服务内部错误 | 重试并联系支持 |
区分额度类与节奏类:E2008 是今天不能再用,E2010 是放慢调用即可恢复,两者的处理方式不同。
B站(含多P合集)、抖音、小红书,以及本地文件上传。其它平台暂未开放,可先用本地文件方式提交。
可以。B站的 videos 数组与上传接口的多文件都支持批量,返回的 task_ids 与提交顺序一一对应。
当前为轮询模型。回调在规划中,上线时以新增字段方式提供,不影响现有调用。
取决于视频时长、网络与当前队列,不同素材差异较大。请按 status 轮询判断,不要按固定时间预期。
与账号套餐的存储策略一致。需要长期保存请在拿到结果后自行落库。