浏览文档
API 参考文档
YouTube 转录文本 API
获取带时间戳的 YouTube 转录文本及完整文本。默认选择自动字幕。
构建请求
填写视频链接中的 11 位 ID,不要填写完整链接。
留空时依次尝试 en-orig、en,返回单轨。也可输入一个代码,或以逗号分隔的最多 10 个不同代码。
https://data.flashdata.dev/v1/queries/realtime参数
发送 source 和 video_id 放在顶层。 数据源选项应放在 params. 可选字段可以省略。
请求体
sourcestring / 必填- 设为 youtube_transcript。
video_idstring / 必填- 11 字符的 YouTube 视频 ID,例如 FUfGcZ092b0。允许字母、数字、下划线和连字符。恰好 11 个字符默认值:
未设置接受的格式
^[A-Za-z0-9_-]{11}$ paramsobject / 可选- 此请求的设置。默认值:
{} callback_urlstring · nullable / 可选- 仅支持异步和批量请求。完成通知 URL 必须是使用 443 端口的公开 HTTPS 地址,最多 2,048 个字符。不得包含用户凭证或 URL 片段。省略、设为 null 或空字符串时不发送通知。批量请求中,需在每个查询上设置此字段,不要放在 params 内部。默认值:
未设置
字幕选择
params.languagestring | array / 可选- 省略时选择英语(先 en-orig,再 en)。auto=true 时,每个语言代码先尝试对应的 -orig 轨,再尝试请求代码。显式 -orig 代码和 auto=false 保持精确选择。数组可请求 1–10 种不同语言。默认值:
en-orig → en params.autoboolean / 可选- true 选择 YouTube 自动生成的字幕;false 选择上传者提供的字幕。此参数选择字幕来源,并非语言检测或生成新转录。
true或false默认值:true
响应
实时请求返回 status: done。在以下位置读取数据源输出: results[0]; usage.credits 记录费用。
读取 segments 可获取带时间戳的文本,fullText 为拼接后的转录文本。片段的 start 和 end 以秒为单位;languageCode 和 isAutoGenerated 用于标识所选字幕轨道。
读取结果
将成功响应的 JSON 保存为 response.json。将以下代码保存为 read-response.py,再运行 python read-response.py。仅使用 Python 标准库,不发起新请求。
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = {
"tracks": result.get("tracks", [result]),
"errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))省略 language 时优先尝试 en-orig,再尝试 en,返回单轨。auto=true 时,每种请求语言先尝试对应的 -orig 轨,再尝试原代码;显式 -orig 和 auto=false 保持精确选择。数组会尝试每种请求语言,按顺序返回 tracks 和 errors。languageCode 标识实际轨道;与请求不同时包含 requestedLanguageCode。
请求语言数组时,请查看 errors 了解哪些字幕轨获取失败。如果未获取到任何字幕轨,请求将失败,已预留的额度会退还。视频提取失败或请求超时也会导致请求失败。
auto 默认 true,选择自动字幕。设为 false 可请求上传者字幕。API 不会切换字幕来源。
API 读取已有 YouTube 字幕,不生成新转录。默认响应包含规范化 JSON 文本;Accept 可选择纯文本,X-Respond-With: markdown 可选择 Markdown。languageName 可以为 null。
多语言
传入语言数组可获取 tracks 和各语言的错误。此示例展示英语可用、西班牙语不可用的情况。
{
"source": "youtube_transcript",
"video_id": "jNQXAC9IVRw",
"params": {
"language": [
"en",
"es"
],
"auto": true
}
}{
"videoId": "jNQXAC9IVRw",
"isAutoGenerated": true,
"tracks": [
{
"videoId": "jNQXAC9IVRw",
"languageCode": "en-orig",
"requestedLanguageCode": "en",
"languageName": null,
"isAutoGenerated": true,
"segments": [
{
"start": 0,
"end": 1.5,
"text": "Hello world."
}
],
"fullText": "Hello world."
}
],
"errors": [
{
"languageCode": "es",
"code": "language_unavailable",
"message": "Auto-generated subtitles not available for language: es"
}
]
}所有响应字段
| 字段 | 描述 |
|---|---|
sourcestring | 请求的 API 数据源。 |
statusstring | 实时请求成功时为 done。 |
created_atstring | 响应创建时间,采用 ISO 8601 格式。 |
usage.creditsnumber | 根据你的套餐,此请求扣除的积分。 |
results[0].videoIdstring | 请求的视频 ID。 |
results[0].languageCodestring | 实际选中的字幕轨道代码,例如 en-orig。 |
results[0].languageNamestring · nullable | 语言显示名称(如有)。 |
results[0].requestedLanguageCodestring · optional | 当请求代码与 languageCode 不同时返回,例如选中 en-orig 时保留请求的 en。 |
results[0].isAutoGeneratedboolean | 所选字幕是否自动生成。 |
results[0].segmentsarray | 按时间顺序排列的字幕分段。 |
results[0].segments[].startnumber | 片段开始时间,单位为秒。 |
results[0].segments[].endnumber | 片段结束时间,单位为秒。 |
results[0].segments[].textstring | 字幕文本。 |
results[0].fullTextstring | 所有分段文本拼接而成的字幕全文。 |
results[0].tracksarray · optional | 仅用于语言数组。按请求顺序返回可用字幕轨;每项包含上述单轨字段。 |
results[0].errorsarray · optional | 仅用于语言数组。按请求顺序返回失败语言;全部成功时为空。 |
results[0].errors[].languageCodestring | 失败的请求语言。 |
results[0].errors[].codestring | 所选字幕轨不存在时为 language_unavailable;无法下载或解析时为 retrieval_failed。 |
results[0].errors[].messagestring | 该语言失败的说明。 |
以上字段对应默认 JSON 响应。JSON、纯文本与 Markdown 格式。
异步请求返回一个任务回执;批量请求则为每个以下条目返回一个回执: 视频 ID。使用返回的链接分别查看每个任务的状态并获取结果。
异步与批量请求生命周期
提交后返回的是回执,而非结果。异步请求创建一个任务;批量请求会在以下字段中为各项返回独立任务: queries[] ,对应每个已接受的查询。请分别跟踪和获取每个任务。
提交到 data.flashdata.dev;从 api.flashdata.dev 读取任务状态与结果,两者使用同一 X-API-Key。以下 API 基础链接提供 Python 与 cURL 示例。
1. 保存任务 ID
切换 Async 时保留该来源的请求字段。使用 Batch 时,将各请求放入 JSON 对象的 queries 数组。保存每个返回的任务 ID。
2. 检查状态
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing:轮询时加入延迟,并遵循Retry-After(如有)。completed:获取结果。failed:检查job.error.读取 job.status,而非提交回执的 status。
任务状态 API 参考文档3. 获取结果
GET https://api.flashdata.dev/v2/jobs/{jobId}/results完成后先认证读取结果地址,再获取 302 存储 URL,不附带 API Key。在完成后的 24 小时内保存 JSON。
结果下载 API 参考文档
轮询和获取现有结果不会消耗查询积分。轮询超时不会取消任务:请保留任务 ID,避免重复提交会产生费用的任务。 错误代码与重试行为.
完成通知 Webhook
按查询订阅
设置 callback_url 放在异步请求的顶层,或 在每个查询内部 放在批量请求中,不要放在以下字段内部: params。无需单独发送 Webhook 注册请求。 实时请求不会发送回调。
使用端口为 443 的公开 HTTPS URL。每个任务达到以下状态时,FlashData 都会通过 POST 发送通知: completed 或 failed;事件包含的是链接,而不是结果本身。
确认接收并验证
返回 2xx ,确保先持久化接收事件。使用以下字段去重: delivery_id,也以以下形式发送: X-Delivery-Id。不会跟随重定向。
投递失败后使用指数退避重试,最多 总共 8 次尝试 ,且最多为 完成后 24 小时。请保留轮询作为备用方式。
回调不带签名。 通过以下接口确认任务 ID、数据源和终态: 需要身份验证的状态端点 ,再处理通知。交付 ID 用于去重,不能作为真实性证明。
Webhook 事件与字段示例
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_transcript",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| 字段 | 描述 |
|---|---|
delivery_idstring | 稳定的投递标识符。使用此值对通知去重;X-Delivery-Id 请求头也会携带此值。 |
idstring | 任务 ID。 |
sourcestring | 请求的数据源。 |
statusstring | completed 或 failed。 |
linksarray | 状态和结果链接。通知不包含结果内容或 API 密钥。 |
links[].relstring | self 或 results。 |
links[].hrefstring | Management API 的绝对 URL;使用你的 API 密钥进行身份验证。 |
links[].methodstring | GET. |
文件批处理
每行上传一个视频 ID,创建 Bulk 任务时设置 source 为 youtube_transcript。共享选项应用于文件中的所有 ID。
来源选项:language, auto。创建 Bulk 任务时放入 options。
以清单和 gzip 压缩的 NDJSON 结果分片形式获取处理完成的整批结果。创建文件批处理任务时设置 options.result_storage,数据类数据源也可将结果分片交付到您的云存储。 请在整个文件批处理任务完成后的 24 小时内保存清单和分片。
错误恢复
如果请求的轨道不可用,请检查 Metadata API 的 transcriptLanguages,并显式请求支持的语言/轨道类型。原样重复选择不可用的轨道并不会创建该轨道。
使用 Metadata 检查可用字幕语言。新请求会消耗查询积分;更换轨道不会修改已有任务。
认证、余额、请求格式及限流错误的处理方法见 API 基础。提交超时可能已创建任务,重试前先检查已有任务。
分步指南:选择转录语言与轨道
价格
| 套餐 | 用量费率每 1,000 次标准请求 | 订阅 | 每个计费周期包含的积分 |
|---|---|---|---|
| 按量付费 | US$0.50 | 无月费 | 按需充值 |
| Micro | US$0.40 | US$49.00 / 月 | 包含 1,000 积分(相当于 US$50.00 的 API 用量) |
| Starter | US$0.35 | US$199.00 / 月 | 包含 4,000 积分(相当于 US$200.00 的 API 用量) |
| Pro | US$0.30 | US$499.00 / 月 | 包含 10,000 积分(相当于 US$500.00 的 API 用量) |
| Scale | US$0.25 | US$999.00 / 月 | 包含 20,000 积分(相当于 US$1,000.00 的 API 用量) |
| Business | US$0.20 | US$1,999.00 / 月 | 包含 40,000 积分(相当于 US$2,000.00 的 API 用量) |
一个账户套餐,三种产品共用积分。由套餐内积分覆盖的用量不会重复收费。
当前价格与套餐限额