浏览文档
API 参考文档
YouTube 扩展搜索 API
每次请求可获取最多 700 条 YouTube 搜索结果,包含视频详情、缩略图,并支持搜索筛选。
构建请求
返回的搜索结果数量上限。
高级参数
https://data.flashdata.dev/v1/queries/realtime参数
发送 source 和 query 放在顶层。 数据源选项应放在 params. 可选字段可以省略。
请求体
sourcestring / 必填- 设为 youtube_search_extended。
querystring / 必填- 搜索查询。1 设为 2,000 个字符默认值:
未设置 paramsobject / 可选- 此请求的设置。默认值:
{} callback_urlstring · nullable / 可选- 仅支持异步和批量请求。完成通知 URL 必须是使用 443 端口的公开 HTTPS 地址,最多 2,048 个字符。不得包含用户凭证或 URL 片段。省略、设为 null 或空字符串时不发送通知。批量请求中,需在每个查询上设置此字段,不要放在 params 内部。默认值:
未设置
结果数量
params.max_resultsinteger / 可选- 请求的结果数量。实际可用结果可能更少。1 设为 700,整数默认值:
20
搜索筛选条件
params.filtersobject · nullable / 可选- 可选的上传日期、结果类型、时长、排序和功能筛选条件。不使用筛选时,可省略或设为 null。默认值:
未设置 params.filters.upload_datestring / 可选- 按上传日期筛选。1 设为 2,000 个字符取值:
today / last_hour / this_week / this_month / this_year默认值:未设置 params.filters.typestring / 可选- 按结果类型筛选。1 设为 2,000 个字符取值:
video / channel / playlist / movie默认值:未设置 params.filters.durationstring / 可选- 按视频时长筛选,以分钟为单位。1 设为 2,000 个字符取值:
<4 / 4-20 / >20默认值:未设置 params.filters.sort_bystring / 可选- 结果排序方式。省略则使用 YouTube 的默认排序。1 设为 2,000 个字符取值:
rating / relevance / view_count / upload_date默认值:未设置 params.filters.360boolean / 可选- 设为 true,要求视频具备 360 功能。
true或false默认值:未设置 params.filters.3dboolean / 可选- 设为 true,要求视频具备 3d 功能。
true或false默认值:未设置 params.filters.4kboolean / 可选- 设为 true,要求视频具备 4k 功能。
true或false默认值:未设置 params.filters.creative_commonsboolean / 可选- 设为 true,要求视频具备 creative commons 功能。
true或false默认值:未设置 params.filters.hdboolean / 可选- 设为 true,要求视频具备 hd 功能。
true或false默认值:未设置 params.filters.hdrboolean / 可选- 设为 true,要求视频具备 hdr 功能。
true或false默认值:未设置 params.filters.liveboolean / 可选- 设为 true,要求视频具备 live 功能。
true或false默认值:未设置 params.filters.locationboolean / 可选- 设为 true,要求视频具备 location 功能。
true或false默认值:未设置 params.filters.purchasedboolean / 可选- 设为 true,要求视频具备 purchased 功能。
true或false默认值:未设置 params.filters.subtitlesboolean / 可选- 设为 true,要求视频具备 subtitles 功能。
true或false默认值:未设置 params.filters.vr180boolean / 可选- 设为 true,要求视频具备 vr180 功能。
true或false默认值:未设置
响应
实时请求返回 status: done。在以下位置读取数据源输出: results[0].results; usage.credits 记录费用。
搜索输出包含 query、totalResults 和返回的条目。totalResults 统计的是此响应中的条目数,并非 YouTube 上所有匹配视频的总数。
读取结果
将成功响应的 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 = [
{"videoId": item.get("videoId"), "title": item.get("title"), "channel": item.get("channel")}
for item in result.get("results", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))max_results 默认为 20,接受 1 到 700。这是一次规模较大的搜索请求,而非 700 个独立的批量请求任务。较大的请求可能耗时更长;异步模式可避免让提交方的连接持续保持打开。
筛选条件应放在 params.filters 中。可用结果可能少于请求数量,条目的详细字段可能为 null 或缺失。Extended Search 使用独立的用量费率。
所有响应字段
| 字段 | 描述 |
|---|---|
sourcestring | 请求的 API 数据源。 |
statusstring | 实时请求成功时为 done。 |
created_atstring | 响应创建时间,采用 ISO 8601 格式。 |
usage.creditsnumber | 根据你的套餐,此请求扣除的积分。 |
results[0].querystring | 搜索查询。 |
results[0].totalResultsinteger | 返回的结果数量。 |
results[0].resultsarray | 按返回顺序排列的搜索结果。 |
results[0].results[].videoIdstring | YouTube 视频 ID。 |
results[0].results[].titlestring | 视频标题。 |
results[0].results[].channelstring | 频道名称。 |
results[0].results[].channelIdstring · nullable | 频道 ID(如有)。 |
results[0].results[].channelUrlstring · nullable | 频道 URL(如有)。 |
results[0].results[].durationnumber · nullable | 视频时长,单位为秒。 |
results[0].results[].durationStringstring · nullable | 格式化的视频时长(如有)。 |
results[0].results[].viewCountnumber · nullable | 观看次数(如有)。 |
results[0].results[].uploadDatestring · nullable | 上传日期(如有)。 |
results[0].results[].descriptionstring · nullable | 描述摘录,最多 500 个字符;不可用时为 null。 |
results[0].results[].thumbnailsarray | 缩略图 URL 和尺寸。 |
以上字段对应默认 JSON 响应。JSON、纯文本与 Markdown 格式。
异步请求返回一个任务回执;批量请求则为每个以下条目返回一个回执: 查询。使用返回的链接分别查看每个任务的状态并获取结果。
异步与批量请求生命周期
提交后返回的是回执,而非结果。异步请求创建一个任务;批量请求会在以下字段中为各项返回独立任务: 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_search_extended",
"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。
认证、余额、请求格式及限流错误的处理方法见 API 基础。提交超时可能已创建任务,重试前先检查已有任务。
分步指南:规划更大的候选搜索