一、适用场景与能力概述全平台视频元数据解析服务为开发者提供了一种结构化的方式从合法可访问的视频/图集分享链接中提取元数据标题、封面、作者、原始URL等。其核心能力覆盖国内主流平台抖音、小红书、B站、快手等及海外5站YouTube、Vimeo、Twitter等并新增支持豆包doubao.com和千问qianwen.com的分享链接解析。二、调用限制与用量边界在集成任何API时明确用量边界是设计稳定系统的前提。本服务的关键限制指标如下指标值说明QPS每秒请求数3 / s单API Key每秒最多3次请求超出返回429 Too Many Requests平均响应时间1.3秒智能缓存多通道竞速优化下的典型延迟月度可用性99.7%含失败重试与自动降级非承诺SLA以实际使用为准URL最大长度2048字符支持短链和完整URLQPS限制解析限制是“每秒钟3次”意味着如果在一秒内连续发送4个请求第4个请求将收到429状态码。开发者应在客户端实现令牌桶或漏桶算法控制请求速率。缓存机制服务内部对已解析的URL进行智能缓存TTL由服务端决定相同URL短时间内重复请求可极快返回。但即便命中缓存仍会计入QPS计数因此不应依赖缓存降低调用频率。响应时间波动平均1.3秒但高峰时段或目标平台响应慢时可能延长。建议设置合理的客户端超时如5秒并结合重试机制处理偶发超时。三、接口鉴权与请求参数请求方式GET请求地址https://v1.apizero.cn/api/video-parse鉴权方式通过HTTP HeaderX-API-Key传递API Key。Query参数参数类型必填说明示例urlstring是待解析的视频/图文链接支持短链https://www.bilibili.com/video/BV1gY411A7y7flatnumber否响应结构模式0双层data默认兼容旧版1单层data推荐1curl 请求示例可直接复制替换$APIZERO_API_KEYcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/video-parse?urlhttps://www.bilibili.com/video/BV1gY411A7y7如果需要单层模式追加flat1curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/video-parse?urlhttps://v.douyin.com/xxxxx/flat1四、返回数据结构解读双层模式flat0默认{ code: 200, message: success, data: { title: 示例视频标题, cover: https://example.com/cover.jpg, author: { name: 作者名, avatar: https://example.com/avatar.jpg }, source: douyin, platform: 抖音, url: https://example.com/video.mp4, type: video, image_urls: [], duration: 120, width: 1080, height: 1920, raw: null }, usage: { used: 45, limit: 1000 } }单层模式flat1推荐{ code: 200, message: success, data: { title: 示例视频标题, cover: https://example.com/cover.jpg, author_name: 作者名, author_avatar: https://example.com/avatar.jpg, source: douyin, platform: 抖音, url: https://example.com/video.mp4, type: video, image_urls: [], duration: 120, width: 1080, height: 1920, raw: null }, usage: { used: 45, limit: 1000 } }关键字段说明source必返回字段标识解析结果来源用于合规追溯。cover视频封面图。url视频直链部分平台有时效性需在有效期内使用。usage当前API Key的已用量和限制量可用于规划调用节奏。五、常见错误与状态码状态码含义处理建议200成功正常解析400请求参数错误如URL格式无效检查url参数是否完整有效401认证失败API Key无效或缺失确认Header中X-API-Key正确429请求过于频繁超出QPS实现客户端限流延迟重试500服务器内部错误或目标平台不可达指数退避重试最多3次特别处理429响应体通常包含Retry-After头部或message字段提示等待秒数。建议使用如下伪代码import time import requests def call_api(url, api_key, max_retries3): for attempt in range(max_retries): resp requests.get( https://v1.apizero.cn/api/video-parse, headers{X-API-Key: api_key}, params{url: url, flat: 1} ) if resp.status_code 200: return resp.json() elif resp.status_code 429: retry_after int(resp.headers.get(Retry-After, 1)) time.sleep(retry_after * (2 ** attempt)) # 指数退避 else: time.sleep(1) raise Exception(Max retries exceeded)六、工程化注意事项1. 并发控制由于QPS限制为3若需要在多线程/异步环境中使用应使用信号量或标准限速库如Java的RateLimiter、Go的time.Ticker。示例Goimport ( net/http time ) var limiter time.NewTicker(333 * time.Millisecond) // 3 QPS ≈ 333ms间隔 func fetchVideoParse(client *http.Client, url string) (*http.Response, error) { -limiter.C // 阻塞直到允许发送 req, _ : http.NewRequest(GET, https://v1.apizero.cn/api/video-parse, nil) req.Header.Set(X-API-Key, apiKey) q : req.URL.Query() q.Add(url, url) q.Add(flat, 1) req.URL.RawQuery q.Encode() return client.Do(req) }2. 重试与退避对于429和5xx错误必须使用退避重试。退避时间建议以1秒为基数指数增长1s, 2s, 4s…最多重试3次。同时避免在已收到大量429后仍高频重试防止API Key被暂时封禁。3. 本地缓存策略对于业务中高频请求的同一URL如审核流程中多次调用可在本地缓存解析结果TTL建议30分钟但须注意本地缓存不应提供超出API自身缓存的时间且必须保留source字段以备合规查询。另外千万不要缓存视频文件本身服务不存储原始内容。4. 合规红线每个解析响应都应保留source字段用于标明数据来源。不得将解析结果用于公开传播版权内容或集成到下载工具中。日志保留期90天超期自动清理开发者应自行管理本地日志的生命周期。七、参考文档接口文档页https://apizero.cn/aidocs/video-parse原始文档https://apizero.cn/aidocs/video-parse/raw.md本文基于接口事实卡撰写所有参数、地址、限制信息以官方最新文档为准。