开放 API

API 文档

通过 RESTful API 将 TranscriptGenerate 集成到您的应用中，以编程方式创建任务、查询结果和管理配额。

概述

Transcript 开放 API 为开发者提供视频文案提取能力，支持提交视频链接异步提取文案，通过轮询获取结果。

工作流程

  1. 调用「创建任务」接口提交视频链接 → 获得 taskId
  2. 使用 taskId 轮询「查询任务」接口 → 等待 status 变为 SUCCESS
  3. 从查询结果中获取 textContent（提取的文案内容）

认证方式

所有接口均需在请求头中携带 API Key 和 API Secret 进行身份验证。

请求头说明示例
X-API-Key您的 API Keyak_1a2b3c4d5e
X-API-Secret您的 API Secretsk_9f8e7d6c5b

请妥善保管您的 API Key 和 Secret，切勿在客户端代码或公开仓库中暴露。

管理 API Key →

认证失败响应

{
  "code": 401,
  "msg": "Missing API Key or Secret. Please include X-API-Key and X-API-Secret in the request headers."
}
🎬

视频文案提取

POST/transcript-api/v1/task/create

创建视频文案提取任务

提交视频链接，创建文案提取任务。任务异步处理，需通过查询接口获取结果。

请求体参数

参数类型必填说明
workUrlString✅视频作品链接（支持抖音、小红书、快手等平台分享链接）
targetLanguageString❌目标语言代码，默认 auto（不翻译）。指定语言代码如 en、ja 可触发翻译，翻译功能仅限会员

请求示例

curl -X POST "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/task/create" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b" \
  -H "Content-Type: application/json" \
  -d '{"workUrl": "https://v.douyin.com/xxxxxx"}'

成功响应

{
  "code": 200,
  "msg": "Task submitted",
  "data": {
    "taskId": "1893456789012345678",
    "status": "WAITING",
    "message": "Task submitted, processing in progress"
  }
}

错误响应

场景codemsg
作品链接为空500Video URL cannot be empty
链接无法识别500Failed to extract a valid platform URL from the input
不支持的平台500This platform is not supported. Please try a different URL.
链接过长500The URL is too long. Please check and try again.
非专业版会员601API access is available for Professional members only. Please upgrade your plan.
并发任务已满601Concurrency limit reached. Please wait for existing tasks to complete.
可用时长不足601Insufficient quota remaining. Please upgrade your plan.
非会员使用翻译601Multi-language translation is available for members only. Please upgrade your plan.
GET/transcript-api/v1/task/query?taskId={taskId}

查询任务状态和结果

根据 taskId 查询任务处理状态，任务完成后返回提取的文案内容。

请求参数

参数类型必填说明
taskIdString✅创建任务时返回的任务ID

请求示例

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/task/query?taskId=1893456789012345678" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

处理中响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "WAITING",
    "errorMessage": null,
    "createTime": "2026-06-04 17:30:00"
  }
}

任务完成响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "SUCCESS",
    "errorMessage": "Video processing succeeded!",
    "textContent": "Full transcript extracted from the video...",
    "title": "Video Title",
    "platform": "DOUYIN",
    "duration": 60.5,
    "videoUrl": "https://example.com/video.mp4",
    "workUrl": "https://v.douyin.com/xxxxxx",
    "cover": "https://example.com/cover.jpg",
    "createTime": "2026-06-04 17:30:00"
  }
}

任务失败响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "FAILURE",
    "errorMessage": "Video processing failed!",
    "createTime": "2026-06-04 17:30:00"
  }
}

响应字段说明

字段类型说明
taskIdString任务唯一标识
statusString任务状态：WAITING(处理中)、SUCCESS(成功)、FAILURE(失败)
errorMessageString状态描述信息
textContentString提取的完整文案文本（仅 SUCCESS 时返回）
titleString视频标题（仅 SUCCESS 时返回）
platformString来源平台：DOUYIN、XHS、KUAISHOU 等
durationNumber视频时长（秒）
videoUrlString视频下载地址
workUrlString原始作品链接
coverString视频封面图地址
createTimeString任务创建时间

错误响应

场景codemsg
taskId为空500Task ID cannot be empty
任务不存在500Task not found
无权查询他人任务500You do not have permission to access this task

建议轮询间隔：2~5秒。大多数视频文案提取在10~30秒内完成。

GET/transcript-api/v1/quota/usage

查询剩余视频转文案权益用量

查询当前账号剩余的视频转文案可用时长。

请求示例

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/quota/usage" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

有限额度响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "unlimited": false,
    "availableSeconds": 3600,
    "availableMinutes": "60.0",
    "totalSeconds": 7200,
    "totalMinutes": "120.0",
    "usedSeconds": 3600,
    "usedMinutes": "60.0",
    "deductionType": "monthly"
  }
}

无限制额度响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "unlimited": true,
    "availableSeconds": -1,
    "availableMinutes": -1,
    "totalSeconds": -1,
    "usedSeconds": 0
  }
}

响应字段说明

字段类型说明
unlimitedBoolean是否为无限制额度
availableSecondsNumber剩余可用秒数（-1表示无限制）
availableMinutesString/Number剩余可用分钟数（-1表示无限制）
totalSecondsNumber总额度秒数（-1表示无限制）
totalMinutesString总额度分钟数
usedSecondsNumber已使用秒数
usedMinutesString已使用分钟数
deductionTypeString扣费周期：monthly(按月重置)、daily(按天重置)
GET/transcript-api/v1/quota/concurrency

查询并发可用量

查询当前账号的并发任务占用情况和可用额度。

请求示例

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/quota/concurrency" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

成功响应

{
  "code": 200,
  "msg": "Success",
  "data": {
    "currentConcurrency": 1,
    "maxConcurrency": 2,
    "availableConcurrency": 1,
    "canAddTask": true
  }
}

响应字段说明

字段类型说明
currentConcurrencyNumber当前正在处理的任务数
maxConcurrencyNumber最大允许并发任务数
availableConcurrencyNumber剩余可用的并发槽位
canAddTaskBoolean是否可以创建新任务

状态码说明

HTTP 状态码

状态码说明
200请求成功
401认证失败（API Key/Secret 缺失或无效）
500业务逻辑错误（详见响应 msg 字段）

业务状态码（code 字段）

code说明
200操作成功
401未授权（API Key/Secret 缺失或无效）
500系统错误（参数校验失败、任务不存在等）
601业务警告（权益不足、权限不够、并发已满等）

任务状态值

status说明
WAITING处理中（包含排队、下载、转文本等阶段）
SUCCESS处理完成，文案已就绪
FAILURE处理失败，查看 errorMessage 了解原因

支持的平台

平台平台代码链接格式示例
抖音DOUYINhttps://v.douyin.com/xxxxxx
小红书XHShttps://www.xiaohongshu.com/discovery/item/xxxxxx
快手KUAISHOUhttps://www.kuaishou.com/short-video/xxxxxx
更多平台—持续扩展中

支持的翻译语言

通过 targetLanguage 参数指定目标语言（仅会员可用）。常用语言代码：

语言代码语言
auto不翻译（默认）
en英语
ja日语
ko韩语
zh中文
fr法语
de德语
es西班牙语

完整语言列表可通过 Transcript 网站查询。

调用频率限制

限制项说明
API Key 每日调用上限由您的套餐决定，在用户中心查看
并发任务上限由您的会员等级决定
建议轮询间隔2~5 秒

错误处理最佳实践

  1. 认证失败（401）— 检查 API Key 和 Secret 是否正确，是否已过期或被禁用
  2. 并发已满 — 先查询并发可用量，等待现有任务完成后再创建新任务
  3. 时长不足 — 查询权益用量确认剩余额度，必要时升级会员
  4. 任务失败 — 可重新提交任务；如反复失败请联系客服
  5. 网络超时 — 建议设置 30 秒请求超时，并实现指数退避重试

Python 调用示例

下载所有 Python 示例脚本，包括创建任务、查询任务、配额查询、并发查询和完整流程示例。

下载 Python 示例代码（.zip）