> For the complete documentation index, see [llms.txt](https://docs.ipwo.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipwo.net/kai-fa-zhe-wen-dang/kuai-su-kai-shi/huo-qu-dai-li-xin-xi/api-dong-tai-huo-qu-jin-dong-tai-dai-li.md). # API 动态获取（仅动态代理） 通过 API 接口动态提取代理 IP 列表，适用于自动化程序、爬虫框架和批量任务场景。 介绍 IPWO 动态住宅代理 API 的认证方式、参数配置、响应格式、代码示例和最佳实践。 API 提取用于动态获取代理 IP 列表，适用于自动化程序和批量任务。 *** ### 🚀 核心说明（重要） * API 提取**仅适用于动态住宅代理**产品 * API 访问通过 [**IP 白名单**](/huo-qu-yu-pei-zhi-dai-li/ip-bai-ming-dan.md)**进行认证** * 返回结果为可用的代理 IP（IP + 端口），可直接用于程序连接 * 每次提取的 IP 均为住宅级真实 IP，具备高匿名性 *** ### ⚡ 使用流程 ``` 1. 配置 IP 白名单（添加服务器公网 IP） ↓ 2. 在控制台获取 API 提取链接 ↓ 3. 调用 API 获取代理 IP 列表 ↓ 4. 在程序中使用返回的 IP:Port ``` *** ### 🔐 第一步：[配置 IP 白名单](https://docs.ipwo.net/) 在调用 API 前，必须先在 IPWO 控制台添加你的服务器公网 IP 到白名单。 **操作步骤** 1. 登录 [IPWO 用户中心](https://www.ipwo.net/) 2. 进入对应代理产品页面（动态住宅代理） 3. 点击「**代理使用**」中的「**IP 白名单**」 4. 点击「**批量添加**」，输入你的服务器公网 IP 5. 点击「**确定**」完成配置 > 👉 你也可以点击「当前IP」后面的「**+**」一键添加当前检测到的 IP > > ❌ 未添加白名单将无法访问 API，会返回 `403 Forbidden` 错误 详细操作请参考 [IP 白名单配置指南](https://docs.ipwo.net/huo-qu-yu-pei-zhi-dai-li/ip-bai-ming-dan)。 *** ### 🌐 第二步：获取 API 提取链接 1. 登录 IPWO 用户中心 2. 进入「**动态住宅代理**」页面 3. 找到「**代理使用**」中的「**API 提取**」 4. 在提取页面中可以配置参数并生成 API 链接 5. 复制生成的 API 链接用于调用 > 👉 API 链接包含你的专属认证信息，请勿泄露给他人 *** ### 📡 第三步：调用 API 获取代理 IP **基本请求** ```bash curl "YOUR_API_LINK" ``` > `YOUR_API_LINK` 为你在控制台生成的 API 提取链接，包含认证信息和参数配置。 **带参数请求示例** ``` curl "YOUR_API_LINK&num=10®ions=US&protocol=http&return_type=json" ``` ### ⚙️ API 参数说明 在控制台生成 API 链接时，或直接在 URL 中追加以下参数： | 参数 | 描述 | 类型 | 必选 | 说明 | | | ------------- | ------- | ------ | --- | ------------------------------------------------------------------------------------- | - | | `num` | IP 提取数量 | int | ✅ 是 | 每次请求提取的 IP 数量，如 `num=10` | | | `regions` | 国家/地区 | string | ❌ 否 | 指定 IP 所在国家，使用国家代码，如 `regions=US`。支持多国家逗号分隔，如 `regions=US,JP,GB` | | | `protocol` | 代理协议 | string | ❌ 否 | `http`：HTTP/HTTPS 代理；`socks5`：SOCKS5 代理。默认 `http` | | | `return_type` | 返回数据格式 | string | ❌ 否 | `json`：JSON 格式（推荐）；`txt`：纯文本格式。默认 `json` | | | `lb` | 行分隔符 | int | ❌ 否 | 当 `return_type=txt` 时生效。`1`：`\r\n`；`2`：`\n`；`3`：`\r`；`4`：`\t`；`5`：自定义分隔符（需配合 `sb` 参数） | | | `sb` | 自定义分隔符 | string | ❌ 否 | 当 `lb=5` 时生效，指定自定义分隔符，如 \`sb= | |
**参数使用示例** ``` # 提取 10 个美国 HTTP 代理 IP，返回 JSON 格式 YOUR_API_LINK&num=10®ions=US&protocol=http&return_type=json # 提取 5 个日本 SOCKS5 代理 IP，返回 TXT 格式，每行一个 YOUR_API_LINK&num=5®ions=JP&protocol=socks5&return_type=txt&lb=1 # 提取 20 个多国家 IP，返回 TXT 格式，用 | 分隔 YOUR_API_LINK&num=20®ions=US,JP,GB&return_type=txt&lb=5&sb=| ``` **常见国家代码** | 国家 | 代码 | 国家 | 代码 | | --- | ---- | ---- | ---- | | 美国 | `US` | 日本 | `JP` | | 英国 | `GB` | 韩国 | `KR` | | 加拿大 | `CA` | 德国 | `DE` | | 法国 | `FR` | 澳大利亚 | `AU` | > 完整国家代码列表请参考 [国家地区参数说明](https://docs.ipwo.net/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/guo-jia-di-qu-can-shu-shuo-ming)。 *** ### 📋 响应格式说明 **JSON 格式响应（推荐）** 当 `return_type=json` 时，返回 JSON 格式数据： **成功响应：** ``` { "code": 0, "success": true, "msg": "操作成功", "request_ip": "127.0.0.1", "data": [ {"ip": "1.1.2.2", "port": 14566}, {"ip": "1.1.2.3", "port": 14577}, {"ip": "1.1.2.4", "port": 14588} ] } ``` **响应字段说明：**
字段类型说明
codeint状态码。0 表示成功，其他值表示错误
successboolean请求是否成功。true 表示成功
msgstring状态描述信息
request_ipstring发起请求的客户端 IP（用于白名单验证排查）
dataarray代理 IP 列表
data[].ipstring代理 IP 地址
data[].portint代理端口
**失败响应示例：** ``` { "code": -1, "success": false, "msg": "白名单未授权", "request_ip": "127.0.0.1", "data": [] } ``` **TXT 格式响应** 当 `return_type=txt` 时，返回纯文本格式（每行一个 `IP:Port`）： ``` 1.1.2.2:14566 1.1.2.3:14577 1.1.2.4:14588 ``` 如果设置了自定义分隔符（`lb=5&sb=|`）： ``` 1.1.2.2:14566|1.1.2.3:14577|1.1.2.4:14588 ``` *** ### 🔥 代码示例 #### **Python** ``` import requests # 替换为你的 API 提取链接 API_URL = "YOUR_API_LINK&num=10®ions=US&protocol=http&return_type=json" def get_proxy_list(): """调用 API 获取代理 IP 列表""" try: response = requests.get(API_URL, timeout=10) result = response.json() if result.get("success") and result.get("data"): proxies = [f"{item['ip']}:{item['port']}" for item in result["data"]] print(f"成功获取 {len(proxies)} 个代理 IP") return proxies else: print(f"获取失败: {result.get('msg')}") return [] except Exception as e: print(f"请求异常: {e}") return [] def use_proxy(proxy_ip, target_url): """使用代理 IP 访问目标网站""" proxies = { "http": f"http://{proxy_ip}", "https": f"http://{proxy_ip}" } try: resp = requests.get(target_url, proxies=proxies, timeout=30) return resp.text except Exception as e: print(f"代理请求失败: {e}") return None if __name__ == "__main__": # 1. 获取代理列表 proxy_list = get_proxy_list() # 2. 使用代理访问目标网站 for proxy in proxy_list: result = use_proxy(proxy, "http://ipinfo.io") if result: print(f"代理 {proxy} 可用，返回: {result[:100]}") ``` #### **Node.js** ``` const https = require('https'); const http = require('http'); // 替换为你的 API 提取链接 const API_URL = 'YOUR_API_LINK&num=10®ions=US&protocol=http&return_type=json'; function getProxyList() { return new Promise((resolve, reject) => { http.get(API_URL, (res) => { let data = ''; res.on('data', (chunk) => data += chunk); res.on('end', () => { try { const result = JSON.parse(data); if (result.success && result.data) { const proxies = result.data.map(item => `${item.ip}:${item.port}`); console.log(`成功获取 ${proxies.length} 个代理 IP`); resolve(proxies); } else { console.log(`获取失败: ${result.msg}`); resolve([]); } } catch (e) { reject(e); } }); }).on('error', reject); }); } (async () => { const proxyList = await getProxyList(); console.log(proxyList); })(); ``` #### **Go** ``` package main import ( "encoding/json" "fmt" "io" "net/http" "time" ) // 替换为你的 API 提取链接 const apiURL = "YOUR_API_LINK&num=10®ions=US&protocol=http&return_type=json" type APIResponse struct { Code int `json:"code"` Success bool `json:"success"` Msg string `json:"msg"` RequestIP string `json:"request_ip"` Data []struct { IP string `json:"ip"` Port int `json:"port"` } `json:"data"` } func getProxyList() ([]string, error) { client := &http.Client{Timeout: 10 * time.Second} resp, err := client.Get(apiURL) if err != nil { return nil, err } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { return nil, err } var result APIResponse if err := json.Unmarshal(body, &result); err != nil { return nil, err } if !result.Success { return nil, fmt.Errorf("API 返回失败: %s", result.Msg) } var proxies []string for _, item := range result.Data { proxies = append(proxies, fmt.Sprintf("%s:%d", item.IP, item.Port)) } return proxies, nil } func main() { proxies, err := getProxyList() if err != nil { fmt.Println("获取代理失败:", err) return } fmt.Printf("成功获取 %d 个代理 IP\n", len(proxies)) for _, p := range proxies { fmt.Println(p) } } ``` *** ### 📊 HTTP 状态码与错误处理 | HTTP 状态码 | 含义 | 常见原因 | 解决方法 | | -------- | ------ | ------------- | ---------------- | | `200` | 请求成功 | — | 正常处理返回数据 | | `403` | 禁止访问 | 服务器 IP 未添加白名单 | 在控制台添加公网 IP 到白名单 | | `400` | 参数错误 | 参数名/参数值格式错误 | 检查 URL 参数拼写和格式 | | `429` | 请求过于频繁 | 短时间内请求次数过多 | 降低请求频率，增加请求间隔 | | `500` | 服务内部错误 | 服务器临时异常 | 稍后重试 | | `503` | 服务不可用 | 维护或临时过载 | 稍后重试 | > 完整错误码说明请参考 [API 错误码](https://docs.ipwo.net/kai-fa-zhe-wen-dang/chang-jian-cuo-wu/api-cuo-wu-ma)。 **错误重试示例（Python）** ``` import requests import time def get_proxy_with_retry(api_url, max_retries=3, interval=2): """带重试机制的 API 调用""" for attempt in range(max_retries): try: response = requests.get(api_url, timeout=10) result = response.json() if result.get("success"): return result["data"] print(f"第 {attempt + 1} 次尝试失败: {result.get('msg')}") except Exception as e: print(f"第 {attempt + 1} 次请求异常: {e}") if attempt < max_retries - 1: time.sleep(interval) return [] ``` *** ### 💡 使用建议 **适用场景** * ✅ 爬虫 / 数据采集（Scrapy、BeautifulSoup 等） * ✅ 自动化测试任务 * ✅ 批量账号注册 / 验证 * ✅ 高并发 IP 轮换场景 **最佳实践**
建议说明
按需获取根据业务需求设置 num 参数，避免一次性提取过多 IP 造成浪费
IP 池管理建议在程序中维护 IP 池，定期调用 API 补充新 IP，淘汰失效 IP
控制频率避免高频调用 API，建议设置合理的请求间隔（如每次提取间隔 ≥ 1 秒）
错误重试对网络错误和 429 状态码实现自动重试机制，配合退避策略
超时设置单个代理请求建议设置 10-30 秒超时，避免长时间阻塞
协议选择大多数场景使用 http 协议即可；需要 UDP 转发或更底层网络操作时使用 socks5
多地区轮换使用 regions 参数指定多个国家，实现 IP 地理分布分散
**IP 池管理参考架构** ``` ──────────────────────────────────────────┐ │ 你的应用程序 │ ├──────────────────────────────────────────┤ │ IP 池管理器（本地） │ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ │ │ 可用 IP │ │ 使用中 │ │ 失效 IP │ │ │ └────┬────┘ └────┬────┘ └─────┬────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────┐ │ │ │ 定时调用 API 补充新 IP │ │ │ └─────────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ IPWO API 提取接口 │ └──────────────────────────────────────────┘ ``` *** ### ❓ 常见问题 #### **API 无法访问？** 请检查： * ✅ 是否已在控制台配置 IP 白名单 * ✅ 添加的是服务器**公网 IP**（非内网 IP） * ✅ 服务器 IP 是否发生变化（动态 IP 需重新添加） * ✅ API 链接是否完整、未被截断 #### **返回 data 为空？** 请检查： * ✅ 账户是否有可用流量 / 资源 * ✅ `regions` 参数指定的国家是否有可用 IP * ✅ `num` 参数是否设置合理（不要超过单次提取上限） * ✅ 是否达到每日提取限额 #### **API 是否需要账号密码？** ❌ 不需要。API 提取仅依赖 **IP 白名单**认证，无需在请求中传入用户名和密码。 #### **提取的 IP 可以用多久？** 提取的 IP 为动态住宅 IP，具有一定的生命周期。建议： * 提取后尽快使用，避免 IP 失效 * 如需长期固定 IP，请使用 [Session 模式](https://docs.ipwo.net/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/session-shi-yong-shuo-ming)（通过用户名密码认证方式） * 程序中实现 IP 健康检查，及时淘汰失效 IP #### **API 调用频率限制是多少？** * 请合理控制调用频率，避免高频请求触发 `429 Too Many Requests` * 建议每次提取间隔 ≥ 1 秒 * 如有大规模提取需求，请联系 IPWO 支持团队调整配额 #### **TXT 和 JSON 格式应该选哪个？** | 格式 | 适用场景 | 优点 | | ------ | ------------- | ----------------- | | `json` | 编程语言直接调用 | 结构化数据，易于解析，包含状态信息 | | `txt` | Shell 脚本、简单工具 | 轻量，可直接管道处理 | > 推荐在程序开发中使用 `json` 格式，便于错误处理和状态判断。 *** ### 👉 下一步 * [IP 白名单配置](https://docs.ipwo.net/huo-qu-yu-pei-zhi-dai-li/ip-bai-ming-dan) → 配置 API 访问权限 * [快速验证](https://docs.ipwo.net/kai-fa-zhe-wen-dang/kuai-su-kai-shi/kuai-su-yan-zheng) → 测试代理是否可用 * [用户名密码认证](https://docs.ipwo.net/kai-fa-zhe-wen-dang/kuai-su-kai-shi/huo-qu-dai-li-xin-xi/yong-hu-ming-mi-ma-ren-zheng) → 另一种代理连接方式 * [代码示例](https://docs.ipwo.net/kai-fa-zhe-wen-dang/dai-ma-shi-li) → 查看更多编程语言示例 * [API 错误码](https://docs.ipwo.net/kai-fa-zhe-wen-dang/chang-jian-cuo-wu/api-cuo-wu-ma) → 完整错误码参考 * [代理参数说明](https://docs.ipwo.net/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/dai-li-can-shu-shuo-ming) → 用户名密码认证参数详解 * [Session 使用说明](https://docs.ipwo.net/kai-fa-zhe-wen-dang/api-shi-yong-zhi-nan/session-shi-yong-shuo-ming) → 固定 IP 会话配置 *** ### 总结 API 提取的核心要点： * 通过 **IP 白名单** 认证，无需账号密码 * 返回 **IP + Port** 列表，支持 JSON / TXT 格式 * 支持指定 **国家、协议、数量、格式** 等参数 * 适用于 **自动化程序、爬虫、批量任务** 场景 * 建议配合 **IP 池管理 + 错误重试** 机制使用