适用场景谁需要追踪短链的每一跳短链如 t.cn、bit.ly 等在日常分享、营销中广泛使用但隐藏了实际目标地址。安全分析人员需要还原完整跳转链以核查是否存在钓鱼重定向运营人员需要分析短链的落地页是否正常开发者在对接第三方服务时也经常需要验证短链的最终地址。本 API 的核心能力是逐跳还原输出每一跳的状态码、跳转方式HTTP Location 或 HTML Meta-Refresh以及耗时相当于给每次短链访问做一次“慢镜头回放”。接口能力边界请求方法GET端点https://v1.apizero.cn/api/unshortQPS 限制5 次/秒超过限制会返回 429最大可追踪跳数通过max_hops参数控制范围 1~30默认 10。如果短链实际跳数超过此值API 只返回前 N 跳并在最后一跳的状态码上标识截断。支持的跳转方式HTTP 301/302/303/307/308 以及 HTMLmeta标签http-equivrefresh的跳转。对于 JavaScript 跳转如 window.location无法直接追踪。适用短链类型绝大多数公开短链服务生成的链接包括但不限于 t.cn、url.cn、dwz.cn、bit.ly、tinyurl.com 等。请求参数与鉴权参数名必填类型说明默认值示例值url是string要展开的原始短链需 URL 编码无https%3A%2F%2Ft.cn%2FA6xxxxmax_hops否number最大追踪跳数1~30105鉴权方式API 使用X-API-Key请求头传递密钥。开发者需先在平台申请 API Key并在每次请求时携带。示例X-API-Key: your_api_key_here注意请求头大小写敏感标准名称为X-API-Key首字母大写、连字符分隔。curl 接入示例可复制以下示例使用环境变量$APIZERO_API_KEY存储 API Key可直接在终端运行。请先设置export APIZERO_API_KEY你的密钥。基础请求默认 10 跳curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx指定最大跳数例如 5 跳curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxxmax_hops5使用 jq 美化输出curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx | jq .注上述示例中的短链https://t.cn/A6xxxx仅为占位请替换为实际短链。返回值深度解读成功响应 HTTP 200Body 为 JSON 对象最外层包含code、msg、data。顶层结构{ code: 0, msg: 成功, data: { original_url: https://t.cn/Aabc, final_url: https://example.com/landing, hops: 2, is_redirect: true, total_time_ms: 412, chain: [ { hop: 1, url: https://t.cn/Aabc, status: 302, method: Location, next: https://example.com/landing, duration_ms: 120 }, { hop: 2, url: https://example.com/landing, status: 200, method: final, duration_ms: 292 } ] } }字段说明字段类型描述original_urlstring传入的原始短链 URLfinal_urlstring最终到达的 URL若无重定向则与 original_url 相同hopsnumber实际追踪到的跳转次数不含最终页is_redirectboolean是否有过重定向与原始 URL 不同total_time_msnumber所有跳转累计耗时毫秒注意这是服务器端请求各跳的总耗时并非客户端实际浏览时间chainarray跳转链数组按hop升序排列chain 元素字段字段类型描述hopnumber跳序号从 1 开始urlstring当前跳请求的 URLstatusnumber当前跳返回的 HTTP 状态码若为final跳则为最终页状态码methodstring跳转方式Location表示通过 HTTP Location 头重定向Meta-Refresh表示通过 HTML meta 刷新跳转final表示追踪结束无后续跳转nextstring仅非 final 跳下一跳的目标 URLduration_msnumber从发起当前跳请求到收到响应的时间毫秒关键要点当method为final时next字段不存在status可能为 200正常或 404/403 等表示最终页状态。若短链实际跳数超过max_hops最后一跳的method仍为final但status中会附带错误标识如 499 表示截断。常见错误与处理建议HTTP 状态码返回 code可能原因处理方式2000成功正常解析 data2001001参数错误如 url 为空或格式非法检查 url 是否 URL 编码2001002认证失败API Key 无效或未携带检查X-API-Key请求头2001003短链解析超时可能目标服务器响应过慢可重试或检查网络连通性2001004跳数超过限制max_hops 超 30 或实际跳数过量适当增加 max_hops最大 30429–请求频率超限降低并发遵守 5 QPS 限制5xx–服务端内部错误等待后重试若持续则反馈平台特别的「截断」场景当 real hops max_hops 时API 仍返回 200但chain最后一跳的method为finalstatus为499自定义标识同时duration_ms只累计到截断处。此时final_url为最后一次成功响应的 URL但可能并非最终落地页。工程化注意事项1. 请求频率控制QPS 为 5意味着单个 API Key 每秒最多发起 5 次请求。在批量处理短链时例如分析 1000 条短链建议采用令牌桶或固定窗口限速将请求间隔控制在 200ms 以上。一个简单的 Go 实现思路import time func rateLimitedRequest(url string, apiKey string) { // 使用 time.Ticker 控制每秒 5 次 ticker : time.NewTicker(time.Second / 5) for _, url : range urls { -ticker.C go sendRequest(url, apiKey) } }2. URL 编码与拼接传入的url参数必须做 URL 编码。例如短链本身含问号、井号时需整体编码。可使用encodeURIComponentJavaScript或urllib.parse.quotePython处理。推荐使用查询字符串构建库或框架自动处理避免手动拼接。3. 超时与重试策略API 本身有超时限制约 15s以具体文档为准。建议客户端设置更严格的超时时间如 10s。对于返回1003或网络错误可采用指数退避重试最多 3 次。4. 结果缓存同一短链在短时间内例如 5 分钟内的跳转链通常不会变化。可在应用层缓存final_url及chain减少重复请求。缓存 key 可用url max_hops拼接的哈希值。注意缓存的 TTL 不宜过长因为某些短链支持自定义跳转目标。5. 对 Meta-Refresh 的特殊处理如果 API 返回method: Meta-Refresh说明目标页面通过meta http-equivrefresh content0;url...跳转。这种跳转需要客户端解析 HTML但本 API 已自动识别。开发者只需关注next字段即可。6. 错误码与日志生产环境中建议记录每次请求的原始返回包括 HTTP 状态码和 code便于异常分析。对于code ! 0或 HTTP 非 200 的情况统一打 warn 日志并关联请求参数。7. 使用场景限制本接口不适用于追踪要求客户端执行 JavaScript 的重定向。某些短链服务可能对机器人访问有限制如 Cloudflare 防护此时 API 可能返回 403 或超时。追踪耗时total_time_ms受网络波动影响单个结果不具备高精度但统计多组数据后可用作趋势参考。实战技巧如何用 Python 批量还原以下是一个简单的 Python 脚本示例假设已安装requestsimport requests import time API_URL https://v1.apizero.cn/api/unshort API_KEY your_api_key_here def unshort(url, max_hops5): headers {X-API-Key: API_KEY} params {url: url, max_hops: max_hops} resp requests.get(API_URL, headersheaders, paramsparams, timeout10) data resp.json() if data.get(code) 0: return data[data] else: raise Exception(fError {data[code]}: {data[msg]}) # 示例用法 short_urls [https://t.cn/A6xxxx, https://bit.ly/3abcde] for su in short_urls: try: result unshort(su, max_hops10) print(f{su} - {result[final_url]} (hops: {result[hops]})) time.sleep(0.3) # 限速 except Exception as e: print(fFailed: {su}, error: {e})需要注意 API Key 不要硬编码在代码仓库中建议通过环境变量或配置中心注入。限速间隔 200ms 可安全运行在 QPS 5 下。参考文档短链还原 API 文档原始 Markdown 文档本文所有示例均基于上述文档提供的真实接口地址与参数编写开发者若遇到与文档不一致之处请以官方文档为准。
