代理API文檔與連接方法

我們整理了如何將IPKite住宅代理連接到代碼和工具，以及查詢餘額、購買記錄、代理列表的開發者API示例。

住宅代理快速入門

購買住宅代理後，會員頁面會顯示代理用戶名和密碼。連接地址只有一個，通過在用戶名中添加值來指定國家、城市和會話。使用以下命令即可立即檢查連接。

購買: 在會員頁面選擇所需GB數量的住宅代理。
確認: 在會員頁面查看代理用戶名(USERNAME)和密碼(PASSWORD)。
連接: 向gw.ipkite.com地址發送請求，使用HTTP 7000端口或SOCKS5 7100端口。

curl -x http://USERNAME:PASSWORD@gw.ipkite.com:7000 https://example.com/

代理連接信息格式

所有住宅代理連接使用相同地址。HTTP和HTTPS請求發送至7000端口，SOCKS5連接發送至7100端口。在用戶名後用連字符(-)附加參數，可根據需要選擇參數。

項目	值	說明
地址	gw.ipkite.com	所有住宅代理連接的訪問地址
HTTP/HTTPS 端口	7000	使用 HTTP 代理連接 HTTP 和 HTTPS 網站
SOCKS5端口	7100	在支援SOCKS5的工具與應用中連接
cc	兩個字母國家代碼（小寫）	例如：cc-us, cc-gb, cc-de
city	城市名稱（小寫，不加空格）	例如：city-newyork, city-london
sess	英文數字會話名稱	使用相同值期間保持相同IP
ttl	1~1,440(分鐘)	固定會話的維持時間

USERNAME-cc-us-city-newyork-sess-a1b2c3-ttl-30:PASSWORD@gw.ipkite.com:7000

輪換代理與固定會話示例

用戶名稱不加sess值時，每次請求將分配新IP的輪換代理；添加sess及ttl則可設定1-1,440分鐘固定時段。需新IP時只需更改sess值。

curl -x http://USERNAME:PASSWORD@gw.ipkite.com:7000 https://example.com/
curl -x http://USERNAME:PASSWORD@gw.ipkite.com:7000 https://example.com/

國家和城市目標示例

透過cc參數可從174國/地區中選擇，並用city參數鎖定主要城市。國家/城市定位功能同時適用於輪轉與固定會話。

curl -x http://USERNAME-cc-de:PASSWORD@gw.ipkite.com:7000 https://example.com/

Python requests代理示例

Python requests中需在proxies值同時填入HTTP與HTTPS的相同代理地址。若需SOCKS5連接，請安裝requests[socks]並將地址改為socks5h://開頭。

import requests

proxy = "http://USERNAME-cc-us-sess-a1b2c3-ttl-30:PASSWORD@gw.ipkite.com:7000"
proxies = {"http": proxy, "https": proxy}

r = requests.get("https://example.com/", proxies=proxies, timeout=30)
print(r.status_code)

Node.js代理示例

Node.js中可使用undici的ProxyAgent或https-proxy-agent套件連接。兩種方法僅需填入單行代理地址。

import { ProxyAgent, fetch } from "undici";

const agent = new ProxyAgent("http://USERNAME-cc-de:PASSWORD@gw.ipkite.com:7000");
const res = await fetch("https://example.com/", { dispatcher: agent });
console.log(res.status);

開發者API認證及基本地址

開發者API採用REST方式，所有回應為JSON格式。在帳戶頁面生成API密鑰後，僅顯示一次的ipk_live_開頭密鑰請立即安全保存。所有請求需在Authorization標頭加入Bearer及API密鑰。

基礎地址: https://ipkite.com/api/v1
驗證標頭: Authorization: Bearer <API金鑰>
調用限制: 每分鐘120次
回應格式: JSON，成功時返回"ok": true

curl https://ipkite.com/api/v1/balance \
  -H "Authorization: Bearer ipk_live_YOUR_API_KEY"

開發者API端點

方法	路徑	內容	主要回應值
GET	/balance	當前餘額	balance, currency
GET	/orders	購買明細列表	code, product, summary, amount, status, created_at
GET	/proxies	已購買代理列表	住宅：username, password, host, http_port, socks_port, traffic_gb_left / 固定IP：ip, port, username, password, country, expires_at

{"ok":true,"balance":"25.00","currency":"USD"}

API錯誤回應及調用限額

若無API密鑰或密鑰錯誤，將返回HTTP 401及以下回應。請檢查標頭名稱、Bearer後空格及完整密鑰。調用限額為每分鐘120次，定期檢查餘額或剩餘流量時建議每分鐘查詢一次以合理使用限額。

{"ok":false,"error":"unauthorized"}