適用場景誰需要追蹤短鏈的每一跳短鏈如 t.cn、bit.ly 等在日常分享、營銷中廣泛使用但隱藏了實際目標(biāo)地址。安全分析人員需要還原完整跳轉(zhuǎn)鏈以核查是否存在釣魚重定向運營人員需要分析短鏈的落地頁是否正常開發(fā)者在對接第三方服務(wù)時也經(jīng)常需要驗證短鏈的最終地址。本 API 的核心能力是逐跳還原輸出每一跳的狀態(tài)碼、跳轉(zhuǎn)方式HTTP Location 或 HTML Meta-Refresh以及耗時相當(dāng)于給每次短鏈訪問做一次“慢鏡頭回放”。接口能力邊界請求方法GET端點https://v1.apizero.cn/api/unshortQPS 限制5 次/秒超過限制會返回 429最大可追蹤跳數(shù)通過max_hops參數(shù)控制范圍 1~30默認(rèn) 10。如果短鏈實際跳數(shù)超過此值A(chǔ)PI 只返回前 N 跳并在最后一跳的狀態(tài)碼上標(biāo)識截斷。支持的跳轉(zhuǎn)方式HTTP 301/302/303/307/308 以及 HTMLmeta標(biāo)簽http-equivrefresh的跳轉(zhuǎn)。對于 JavaScript 跳轉(zhuǎn)如 window.location無法直接追蹤。適用短鏈類型絕大多數(shù)公開短鏈服務(wù)生成的鏈接包括但不限于 t.cn、url.cn、dwz.cn、bit.ly、tinyurl.com 等。請求參數(shù)與鑒權(quán)參數(shù)名必填類型說明默認(rèn)值示例值url是string要展開的原始短鏈需 URL 編碼無https%3A%2F%2Ft.cn%2FA6xxxxmax_hops否number最大追蹤跳數(shù)1~30105鑒權(quán)方式API 使用X-API-Key請求頭傳遞密鑰。開發(fā)者需先在平臺申請 API Key并在每次請求時攜帶。示例X-API-Key: your_api_key_here注意請求頭大小寫敏感標(biāo)準(zhǔn)名稱為X-API-Key首字母大寫、連字符分隔。curl 接入示例可復(fù)制以下示例使用環(huán)境變量$APIZERO_API_KEY存儲 API Key可直接在終端運行。請先設(shè)置export APIZERO_API_KEY你的密鑰?；A(chǔ)請求默認(rèn) 10 跳curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx指定最大跳數(shù)例如 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僅為占位請?zhí)鎿Q為實際短鏈。返回值深度解讀成功響應(yīng) HTTP 200Body 為 JSON 對象最外層包含code、msg、data。頂層結(jié)構(gòu){ 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最終到達(dá)的 URL若無重定向則與 original_url 相同hopsnumber實際追蹤到的跳轉(zhuǎn)次數(shù)不含最終頁is_redirectboolean是否有過重定向與原始 URL 不同total_time_msnumber所有跳轉(zhuǎn)累計耗時毫秒注意這是服務(wù)器端請求各跳的總耗時并非客戶端實際瀏覽時間chainarray跳轉(zhuǎn)鏈數(shù)組按hop升序排列chain 元素字段字段類型描述hopnumber跳序號從 1 開始urlstring當(dāng)前跳請求的 URLstatusnumber當(dāng)前跳返回的 HTTP 狀態(tài)碼若為final跳則為最終頁狀態(tài)碼methodstring跳轉(zhuǎn)方式Location表示通過 HTTP Location 頭重定向Meta-Refresh表示通過 HTML meta 刷新跳轉(zhuǎn)final表示追蹤結(jié)束無后續(xù)跳轉(zhuǎn)nextstring僅非 final 跳下一跳的目標(biāo) URLduration_msnumber從發(fā)起當(dāng)前跳請求到收到響應(yīng)的時間毫秒關(guān)鍵要點當(dāng)method為final時next字段不存在status可能為 200正?；?404/403 等表示最終頁狀態(tài)。若短鏈實際跳數(shù)超過max_hops最后一跳的method仍為final但status中會附帶錯誤標(biāo)識如 499 表示截斷。常見錯誤與處理建議HTTP 狀態(tài)碼返回 code可能原因處理方式2000成功正常解析 data2001001參數(shù)錯誤如 url 為空或格式非法檢查 url 是否 URL 編碼2001002認(rèn)證失敗API Key 無效或未攜帶檢查X-API-Key請求頭2001003短鏈解析超時可能目標(biāo)服務(wù)器響應(yīng)過慢可重試或檢查網(wǎng)絡(luò)連通性2001004跳數(shù)超過限制max_hops 超 30 或?qū)嶋H跳數(shù)過量適當(dāng)增加 max_hops最大 30429–請求頻率超限降低并發(fā)遵守 5 QPS 限制5xx–服務(wù)端內(nèi)部錯誤等待后重試若持續(xù)則反饋平臺特別的「截斷」場景當(dāng) real hops max_hops 時API 仍返回 200但chain最后一跳的method為finalstatus為499自定義標(biāo)識同時duration_ms只累計到截斷處。此時final_url為最后一次成功響應(yīng)的 URL但可能并非最終落地頁。工程化注意事項1. 請求頻率控制QPS 為 5意味著單個 API Key 每秒最多發(fā)起 5 次請求。在批量處理短鏈時例如分析 1000 條短鏈建議采用令牌桶或固定窗口限速將請求間隔控制在 200ms 以上。一個簡單的 Go 實現(xiàn)思路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參數(shù)必須做 URL 編碼。例如短鏈本身含問號、井號時需整體編碼?？墒褂胑ncodeURIComponentJavaScript或urllib.parse.quotePython處理。推薦使用查詢字符串構(gòu)建庫或框架自動處理避免手動拼接。3. 超時與重試策略API 本身有超時限制約 15s以具體文檔為準(zhǔn)。建議客戶端設(shè)置更嚴(yán)格的超時時間如 10s。對于返回1003或網(wǎng)絡(luò)錯誤可采用指數(shù)退避重試最多 3 次。4. 結(jié)果緩存同一短鏈在短時間內(nèi)例如 5 分鐘內(nèi)的跳轉(zhuǎn)鏈通常不會變化。可在應(yīng)用層緩存final_url及chain減少重復(fù)請求。緩存 key 可用url max_hops拼接的哈希值。注意緩存的 TTL 不宜過長因為某些短鏈支持自定義跳轉(zhuǎn)目標(biāo)。5. 對 Meta-Refresh 的特殊處理如果 API 返回method: Meta-Refresh說明目標(biāo)頁面通過meta http-equivrefresh content0;url...跳轉(zhuǎn)。這種跳轉(zhuǎn)需要客戶端解析 HTML但本 API 已自動識別。開發(fā)者只需關(guān)注next字段即可。6. 錯誤碼與日志生產(chǎn)環(huán)境中建議記錄每次請求的原始返回包括 HTTP 狀態(tài)碼和 code便于異常分析。對于code ! 0或 HTTP 非 200 的情況統(tǒng)一打 warn 日志并關(guān)聯(lián)請求參數(shù)。7. 使用場景限制本接口不適用于追蹤要求客戶端執(zhí)行 JavaScript 的重定向。某些短鏈服務(wù)可能對機器人訪問有限制如 Cloudflare 防護(hù)此時 API 可能返回 403 或超時。追蹤耗時total_time_ms受網(wǎng)絡(luò)波動影響單個結(jié)果不具備高精度但統(tǒng)計多組數(shù)據(jù)后可用作趨勢參考。實戰(zhàn)技巧如何用 Python 批量還原以下是一個簡單的 Python 腳本示例假設(shè)已安裝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 不要硬編碼在代碼倉庫中建議通過環(huán)境變量或配置中心注入。限速間隔 200ms 可安全運行在 QPS 5 下。參考文檔短鏈還原 API 文檔原始 Markdown 文檔本文所有示例均基于上述文檔提供的真實接口地址與參數(shù)編寫開發(fā)者若遇到與文檔不一致之處請以官方文檔為準(zhǔn)。