YouTube 缩略图下载器 API
一次带鉴权的 POST 返回任意公开 YouTube 视频缩略图的直接 CDN 图片链接——画质选择器带自动回退，干净 JSON。
- 单一 REST 端点
- 带回退的画质
- 所有链接形态
- 稳定响应字段
- 幂等的计费写入
- 可预期的错误码
请求示例
curl -X POST "https://api.agentbody.io/v1/youtube/thumbnail/download" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"quality":"maxresdefault","url":"YOUR_URL"}'响应示例
来自 OpenAPI 规范的已文档化响应。
Direct thumbnail image link and normalized public video metadata.
{
"quality": "maxresdefault",
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"video_id": "dQw4w9WgXcQ"
}功能特点
用 YouTube 缩略图 API 搭建内容调研管线、设计工具和媒体库——视频 URL 进，CDN 图片链接出。
单一 REST 端点
带 bearer API 密钥和视频 URL 调用 POST /v1/youtube/thumbnail/download。API 解析视频并返回缩略图的直接 CDN 链接——无需截图工具、无需页面爬取。
带回退的画质
quality 传 maxresdefault、sddefault、hqdefault 或 mqdefault。请求档位不存在时，操作自动回退到可用最高档并回报实际服务的画质。
所有链接形态
watch URL、Shorts 链接、直播 URL、embed 链接、youtu.be 链接全部解析。集成侧用户粘什么都能处理，省一步归一化。
稳定响应字段
每个响应带 thumbnail_url、quality、video_id 和规范视频 url——管线可直接存储和关联的字段，无需逐请求解析。
幂等的计费写入
缩略图获取是按量计费操作。重试时带 Idempotency-Key 头，中断的响应不会重复计费同一视频——同键相同请求返回原始结果。
可预期的错误码
文档化状态码：400 请求无效、401 密钥缺失或错误、409 幂等冲突、502/503/504 暂时性上游问题——每类对应明确的修复或重试动作。
使用步骤
按以下步骤调用 YouTube 缩略图 API：创建密钥，构造 POST 请求，处理返回的 CDN 链接。
创建 API 密钥
创建 AgentBody 账号并在控制台生成 API 密钥。密钥留在服务端并以 bearer 令牌发送——绝不进浏览器代码。
构造请求
向 /v1/youtube/thumbnail/download 发送 POST，带必填的 url 和可选的 quality。生成示例展示五种语言的确切请求。
加幂等键
给每个可能重试的获取附 Idempotency-Key 头。同键相同请求返回原始响应，不重复计费。
密钥留在服务端
从后端、serverless 函数或定时任务调用端点。若终端用户触发获取，经你自己的端点代理。
解析 JSON 响应
读取返回的 thumbnail_url、quality、video_id、url。把 CDN 链接和所属视频一起存储——字段跨请求稳定。
正确处理错误
400 修请求体，401 配好密钥，409 按文档化幂等键行为处理。502/503/504 同键带退避重试。
常见问题
YouTube 缩略图下载器 API 是什么？
一个带鉴权的 POST 端点 /v1/youtube/thumbnail/download，从任意链接形态解析公开 YouTube 视频，返回缩略图的直接 CDN 图片 URL——画质选择器（maxresdefault 到 mqdefault），档位不可用时自动回退。
缩略图 API 支持哪些分辨率？
maxresdefault、sddefault、hqdefault、mqdefault。默认请求 max 档；该档不存在时 API 回退到可用最高画质并回报实际服务的档位。
价格怎么算？
每次缩略图获取是消耗账号额度的按量计费操作。价格由网关管理而非本页写死——控制台查单价，用幂等键确保重试不双重计费。
API 接受哪些 URL 格式？
watch URL、Shorts 链接、直播 URL、embed 链接、youtu.be 短链——端点从任何链接形态识别视频。
能通过 API 按链接下载 YouTube 缩略图吗？
能——POST 视频链接（watch、Shorts、直播、embed 或 youtu.be），响应以 JSON 返回 thumbnail_url、quality、video_id 和规范视频 URL。一条链接一次请求；批量管线逐条迭代即可。
缩略图 API 多少钱？
每次获取是消耗账号额度的按量计费操作。价格由网关管理——控制台查当前单价。幂等键确保重试不双重计费。
私密或不公开的视频支持吗？
不支持。端点只读取公开视频——私密、隐藏的不公开视频和已删除内容不会解析，也不索要 YouTube 凭据。
怎么处理 API 错误？
400 修请求体，401 修 bearer 密钥，409 按文档化幂等键行为处理。把 502、503、504 当作暂时性上游故障，同键带退避重试。