浏览文档
API 参考文档
MCP 工具与结构
查看 FlashData MCP 的工具参数、默认值、账户读取、任务状态与结果获取方式。
本页内容
OAuth、Codex、OpenClaw 与 API Key 接入方式
传输与认证
托管 MCP 通过以下地址提供 Streamable HTTP 服务。API Key 连接需发送 X-API-Key 请求头;工具访问受来源权限及可用 Credits 限制。
URL: https://data.flashdata.dev/mcp
X-API-Key: <your API key>把实际 FlashData API Key 保存在客户端的凭据配置中。不要把它发到对话里或填入工具参数。此处介绍 API Key 连接;OAuth 登录和已验证的 Codex、OpenClaw 配置见智能体访问指南。youtube_download 提供异步媒体下载,需要相应 API Key 权限。
管理 API Key查询工具
客户端会发现密钥有权限使用的工具。全部 6 个 Google 和 8 个 YouTube 数据工具默认实时执行,也可以设置 mode 为 async。submit_batch 支持这两类数据查询。youtube_download 使用正式 Download API,必填用户 storage,支持异步或 submit_batch 批量。模型可根据任务自行选择与组合工具。
google_search · google_images · google_news · google_shopping · google_videos · google_places
YouTube
youtube_search · youtube_search_extended · youtube_metadata · youtube_transcript · youtube_captions · youtube_trainability · youtube_channel · youtube_suggestions · youtube_download
{
"query": "MCP protocol",
"num": 3,
"gl": "us",
"hl": "en",
"mode": "async"
}工具参数
MCP 查询参数直接放在工具 arguments 对象中,例如 query、num、language 和 mode,不使用 REST API 的 params 包装。单个查询工具由工具名决定 source;submit_batch 的每一项才需要 source。工具不接收 API Key 或 callback_url。以下 JSON 是工具参数对象,可以通过客户端的 callTool({ name, arguments }) 传入。
布尔值使用 true/false,整数使用数字,不能用字符串代替。未列出的字段会被拒绝。14 个数据查询工具的 mode 可选 realtime 或 async,默认 realtime;批量每项不接受 mode。
| 工具 | 必填参数 | 可选参数与默认值 |
|---|---|---|
youtube_download | video_id, storage | mode 仅支持 async(默认)。download_type:audio_video(默认)/video/audio;video_quality:默认 <=720,可用 best/worst 或 <=、==、>= 加 144/360/480/720/1080/1440/2160/4320;fps:同样的比较符加 1–240。output_format:视频 mp4(默认)/webm/mkv,音频 m4a(默认)/mp3/opus。audio_language:default/original;audio_quality:best/320/256/192/128,仅音频。yt_dlp_format:最多 1024 字符,覆盖画质、帧率和语言选择。纯音频不传 video_quality/fps,纯视频不传 audio_language。storage 必填,结构与正式 API 的 params.storage 相同。start_at/end_at:HH:MM:SS,最多 12 小时,end_at 必须晚于 start_at;upload_metadata:布尔值,默认 false。批量每条下载都必须提供 storage。不接受 browser_delivery 或 callback_url。 |
storage | storage_type, storage_url | storage_url 为用户桶名(Azure 为容器名),不是本机目录。storage_type:s3/s3_compatible/oss/gcs/azure/cos/bos/tos;object_prefix:可选文件前缀。S3、S3-compatible、OSS、COS、BOS、TOS 使用 access_key/secret_key 及相应 region/endpoint_url;GCS 使用 service_account(project_id、client_email、private_key);Azure 使用 account_name、具有写权限的容器 sas_token。endpoint 必须可从 Worker 访问。凭据从你的存储配置读取,不要粘贴进聊天或回显。 |
google_* | query | query:1–2,000 字符。gl:2 字母国家码;hl:1–35 字符语言码;location/tbs:1–200 字符;num/page:1–100 整数;autocorrect:布尔值。省略时按搜索服务行为处理,不保证固定国家、语言或结果数量。 |
youtube_search | query | query:1–2,000 字符。max_results:1–20,默认 20;filters:筛选对象,省略或 null 表示不筛选。 |
youtube_search_extended | query | query:1–2,000 字符。max_results:1–700,默认 20;filters:与标准搜索相同。 |
youtube_metadata | video_id | include_formats 和 include_chapters:布尔值,均默认 true。 |
youtube_transcript | video_id | 省略 language 时优先 en-orig,再尝试 en,返回单轨。auto=true 时每种语言先尝试对应的 -orig 轨,再尝试原代码;显式 -orig 和 auto=false 保持精确选择。数组会尝试所有 1–10 种请求语言,按顺序返回 tracks 和 errors。auto 默认 true,选择自动字幕。 |
youtube_captions | video_id | 省略 language 时优先 en-orig,再尝试 en,返回单轨。auto=true 时每种语言先尝试对应的 -orig 轨,再尝试原代码;显式 -orig 和 auto=false 保持精确选择。数组会尝试所有 1–10 种请求语言,按顺序返回 tracks 和 errors。auto 默认 false,选择上传者字幕。 |
youtube_trainability | video_id | 除 mode 外无可选参数。检查 Creative Commons 许可分类,不代表授予训练权限。 |
youtube_channel | handle | handle:1–100 字符;video_limit:1–100,默认 20。 |
youtube_suggestions | query | query:1–2,000 字符;language:默认 en;region:2 字母国家码,默认 US。 |
video_id 必须是 11 字符的 YouTube ID,只含字母、数字、下划线或连字符,不填写完整视频 URL。每个语言代码为 1–35 字符,只含字母、数字或连字符。字幕 auto=true 选择自动字幕,false 选择上传者字幕,不会自动在两类字幕间回退。请求语言数组时,即使任务成功也请检查 errors。
YouTube 搜索筛选
filters.type:video/channel/playlist/movie;upload_date:today/last_hour/this_week/this_month/this_year;duration:<4、4-20 或 >20;sort_by:rating/relevance/view_count/upload_date。以下字段均为布尔值,true 表示要求该特性:360、3d、4k、creative_commons、hd、hdr、live、location、purchased、subtitles、vr180。
{
"query": "renewable energy",
"max_results": 5,
"filters": {
"type": "video",
"duration": "<4",
"subtitles": true
}
}账户查询(免费)
get_balance 查询账户余额;get_pricing 查询套餐单价和调用成本预估;get_limits 查询套餐上限和当前排队数;get_usage 汇总最近 7 天用量(最多查询 31 天)。用量覆盖当前 Key 授权来源在整个账户的请求,统计可能有延迟。
get_balance 和 get_limits 使用空参数 {}。get_pricing 的 source 可选,省略时返回 Key 授权的 MCP 查询来源价格;request_count 为 1–100000 的整数,默认 1,表示请求次数,分页和批量每项分别算一次。get_usage 的 source 可选,省略时汇总 Key 授权的全部来源,也可读取 youtube_download 的用量。下载价格返回 creditsPerTb(1 TB = 10^12 字节),按实际上传字节结算并预留额度;request_count 不适用于下载,estimatedCredits 为 null。
get_usage 的 from/to 使用 UTC ISO 时间,例如 2026-09-21T00:00:00Z,可含 1–3 位小数秒。from 含边界,to 不含边界,向下对齐分钟;默认 7 天、最多 31 天。只传 from 时,to 为 7 天后;只传 to 时,from 为 7 天前。具体返回窗口以响应中的 from/to 为准。
{
"source": "google_search",
"request_count": 3
}{
"source": "youtube_metadata",
"from": "2026-09-21T00:00:00Z",
"to": "2026-09-22T00:00:00Z"
}任务与大结果
异步请求返回任务 id,使用 get_job 的 job_id 参数读取 job.status;任务完成后,output 包含原始查询响应;下载返回上传结果,其中 output.results[0].file_url 指向用户存储,另有 file_size、downloaded_bytes、md5 等字段。私有文件需使用用户存储自身的认证方式访问。JSON 结果保留 24 小时;媒体文件的保留与访问策略由用户存储决定。submit_batch 接受至少一条 Google 或 YouTube 查询(含下载),每项包含 source 和该来源的平铺参数。每项分别计费,批量数量与待处理任务上限由套餐决定。读取任务不会再次扣费。MCP 不提供文件式 Bulk 工具。
{
"video_id": "FUfGcZ092b0",
"language": "en",
"auto": true,
"mode": "async"
}{
"queries": [
{
"source": "google_search",
"query": "renewable energy",
"num": 3
},
{
"source": "youtube_metadata",
"video_id": "FUfGcZ092b0",
"include_formats": false
}
]
}将示例中的 job_id/result_id/offset 替换为实际响应中的值,不要重新提交查询来获取下一段结果。
{
"job_id": "job_REPLACE_WITH_RETURNED_ID"
}较大响应返回 JSON 文本分段、result_id 和 next_offset。使用同一把 Key 调用 get_result,必填 result_id;offset 为非负整数,默认 0,续读时填写上次的 next_offset;limit 为 1–16000 的整数,默认 16000,单位是 UTF-16 code units,不是字节或结果条数。按偏移拼接全部 chunk 后解析 JSON,next_offset=null 表示结束。缓存有效期 10 分钟,每把 Key 最多保留 4 个大结果,可能提前被淘汰。读取分段不重复查询或扣费。
{
"result_id": "result_1800000000000_00000000-0000-0000-0000-000000000000",
"offset": 16000,
"limit": 16000
}计费与错误
查询按现有套餐单价扣除 Credits,MCP 不额外扣费。业务错误使用 isError 标记,并保留上游 HTTP 状态与请求 ID。余额不足时先补充额度;权限不足时检查密钥权限。
查询超时或连接中断不代表任务未执行。遇到 query_outcome_unknown,先在控制台的请求记录中检查,再决定是否重提。不要自动重试付费提交;读取已有任务或分段可以重试。单个上游响应最大 4 MiB,建议限制搜索数量;超出限制也可能已扣费。
使用 JavaScript 客户端验证
以下代码使用已验证的官方 SDK 1.30.0,通过 Streamable HTTP 连接并列出工具,不执行付费查询。把代码保存为 mcp-check.mjs,在环境中配置 FLASHDATA_API_KEY 后运行 node mcp-check.mjs。
npm install @modelcontextprotocol/[email protected]import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new Client({ name: 'my-app', version: '1.0.0' });
try {
await client.connect(new StreamableHTTPClientTransport(
new URL('https://data.flashdata.dev/mcp'),
{ requestInit: { headers: { 'X-API-Key': key } } }
));
console.log((await client.listTools()).tools.map(tool => tool.name));
} finally {
await client.close();
}