跳转到正文
中文
获取 API 密钥
浏览文档

API 参考文档

YouTube 视频元数据 API

获取 API 密钥

通过 YouTube 视频 ID 获取视频元数据,包括频道详情、互动统计、缩略图、可用格式和章节。

构建请求

填写视频链接中的 11 位 ID,不要填写完整链接。

POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_metadata",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "include_formats": False,
        "include_chapters": True,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
结果包含在 HTTP 响应中X-API-Key 身份验证

参数

发送 source 和 video_id 放在顶层。 数据源选项应放在 params. 可选字段可以省略。

请求体

sourcestring / 必填
设为 youtube_metadata。
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.include_formatsboolean / 可选
包含可用媒体格式及其编解码器、分辨率和比特率信息。
true 或 false默认值: true
params.include_chaptersboolean / 可选
视频有章节时,包含章节信息。
true 或 false默认值: true

响应

实时请求返回 status: done。在以下位置读取数据源输出: results[0]; usage.credits 记录费用。

单个视频的元数据包含 videoId、标题、频道详情、时长和互动统计。

读取结果

将成功响应的 JSON 保存为 response.json。将以下代码保存为 read-response.py,再运行 python read-response.py。仅使用 Python 标准库,不发起新请求。

read-response.py
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 = {name: result.get(name) for name in (
    "videoId", "title", "channel", "duration", "hasTranscripts", "transcriptLanguages"
)}
print(json.dumps(output, ensure_ascii=False, indent=2))

两个响应选项省略时均默认为 true。仅需要元数据时,可禁用 include_formats 以缩小响应。章节信息仅在请求且可用时出现。不可用的计数可能为 null。

formats 描述可用编码格式;它不会下载视频。 hasTranscripts 和 transcriptLanguages 描述可用性,而不是字幕文本。请使用 Download API ,用于媒体,以及 转录文本 API ,用于文本。

所有响应字段
字段描述
sourcestring请求的 API 数据源。
statusstring实时请求成功时为 done。
created_atstring响应创建时间,采用 ISO 8601 格式。
usage.creditsnumber根据你的套餐,此请求扣除的积分。
results[0].videoIdstringYouTube 视频 ID。
results[0].titlestring视频标题。
results[0].descriptionstring完整视频描述。
results[0].channelstring频道名称。
results[0].channelIdstring频道 ID。
results[0].channelUrlstring频道 URL。
results[0].channelSubscriberCountnumber · nullable频道订阅者数量。
results[0].viewCountnumber · nullable观看次数。
results[0].likeCountnumber · nullable点赞数。
results[0].commentCountnumber · nullable评论数量。
results[0].uploadDatestring · nullable上传日期。
results[0].durationnumber · nullable视频时长,单位为秒。
results[0].durationStringstring · nullable格式化的时长(如有)。
results[0].thumbnailsarray缩略图 URL 和尺寸。
results[0].categoriesarray视频类别。
results[0].tagsarray视频标签。
results[0].ageLimitinteger年龄限制;无限制时为 0。
results[0].isLiveboolean视频当前是否正在直播。
results[0].wasLiveboolean视频是否曾为直播。
results[0].hasTranscriptsboolean是否有可用字幕。
results[0].transcriptLanguagesarray可用字幕语言代码。
results[0].formatsarray · optionalinclude_formats 为 true 时返回的可用媒体格式。
results[0].chaptersarray · optional章节标题,以及以秒为单位的 start_time 和 end_time,仅在请求且可用时返回。

以上字段对应默认 JSON 响应。JSON、纯文本与 Markdown 格式。

异步请求返回一个任务回执;批量请求则为每个以下条目返回一个回执: 视频 ID。使用返回的链接分别查看每个任务的状态并获取结果。

异步与批量请求生命周期

提交后返回的是回执,而非结果。异步请求创建一个任务;批量请求会在以下字段中为各项返回独立任务: queries[] ,对应每个已接受的查询。请分别跟踪和获取每个任务。

提交到 data.flashdata.dev;从 api.flashdata.dev 读取任务状态与结果,两者使用同一 X-API-Key。以下 API 基础链接提供 Python 与 cURL 示例。

  1. 1. 保存任务 ID

    切换 Async 时保留该来源的请求字段。使用 Batch 时,将各请求放入 JSON 对象的 queries 数组。保存每个返回的任务 ID。

    Async 请求与回执 · Batch 请求体

  2. 2. 检查状态

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing:轮询时加入延迟,并遵循 Retry-After (如有)。 completed:获取结果。 failed:检查 job.error.

    读取 job.status,而非提交回执的 status。

    检查状态 · Python 与 cURL

    任务状态 API 参考文档
  3. 3. 获取结果

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    完成后先认证读取结果地址,再获取 302 存储 URL,不附带 API Key。在完成后的 24 小时内保存 JSON。

    获取结果 · Python 与 cURL · 响应格式

    结果下载 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_metadata",
  "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请求的数据源。
statusstringcompleted 或 failed。
linksarray状态和结果链接。通知不包含结果内容或 API 密钥。
links[].relstringself 或 results。
links[].hrefstringManagement API 的绝对 URL;使用你的 API 密钥进行身份验证。
links[].methodstringGET.

完整 Webhook 协议与 URL 限制

文件批处理

每行上传一个视频 ID,创建 Bulk 任务时设置 source 为 youtube_metadata。共享选项应用于文件中的所有 ID。

来源选项:include_formats, include_chapters。创建 Bulk 任务时放入 options。

以清单和 gzip 压缩的 NDJSON 结果分片形式获取处理完成的整批结果。创建文件批处理任务时设置 options.result_storage,数据类数据源也可将结果分片交付到您的云存储。 请在整个文件批处理任务完成后的 24 小时内保存清单和分片。

Bulk 处理 API · Python 与 cURL · Batch JSON 请求

为此来源构建 Bulk 工作流 · 暂停、恢复与错误处理

错误恢复

提供 11 字符的视频 ID,而不是完整的 YouTube URL。有效 ID 不保证视频可访问:已移除、私有或受限制的视频可能在处理时失败。缺失的计数可能为 null;缺少章节或格式本身并不代表任务失败。

认证、余额、请求格式及限流错误的处理方法见 API 基础。提交超时可能已创建任务,重试前先检查已有任务。

错误与状态码 · 何时重试 · 速率限制

分步指南:获取并使用视频元数据

价格

套餐用量费率每 1,000 次标准请求订阅每个计费周期包含的积分
按量付费US$0.50无月费按需充值
MicroUS$0.40US$49.00 / 月包含 1,000 积分(相当于 US$50.00 的 API 用量)
StarterUS$0.35US$199.00 / 月包含 4,000 积分(相当于 US$200.00 的 API 用量)
ProUS$0.30US$499.00 / 月包含 10,000 积分(相当于 US$500.00 的 API 用量)
ScaleUS$0.25US$999.00 / 月包含 20,000 积分(相当于 US$1,000.00 的 API 用量)
BusinessUS$0.20US$1,999.00 / 月包含 40,000 积分(相当于 US$2,000.00 的 API 用量)

一个账户套餐,三种产品共用积分。由套餐内积分覆盖的用量不会重复收费。

当前价格与套餐限额